SBT plugin that generates a swagger-ui site for static website hosting.
Add the following to your project/plugins.sbt:
addSbtPlugin("com.fgrutsch" % "sbt-swagger-ui" % "x.x.x")After that you just need to enable the plugin on your SBT project and configure the OpenAPIs you want to serve:
import com.fgrutsch.sbt.swaggerui.SwaggerUiConfig
lazy val docs = project
.in(file("docs"))
.enablePlugins(SwaggerUiPlugin)
.settings(
swaggerUiConfig := swaggerUiConfig.value.addUrls(
SwaggerUiConfig.Url.File(
"Petstore Api",
sourceDirectory.value / "main" / "scala" / "docs" / "api" / "petstore.json"
),
SwaggerUiConfig.Url.Remote(
"Github API",
"https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.json"
)
)
)This would add two OpenAPIs to the swagger-ui site, one that is served from a local file (Petstore API) and one from a remote location (Github API).
Check com.fgrutsch.sbt.swaggerui.SwaggerUiConfig for a full set of configuration values.
To generate the swagger-ui site you just need to run sbt docs/swaggerUiGenerate and check the output in the directory you configured (swaggerUiDirectory).
You might already use sbt-site to generate a static documentation website. You can easily integrate sbt-swagger-ui by mapping the output of sbt-swagger-ui to sbt-site's directory:
import com.fgrutsch.sbt.swaggerui.SwaggerUiConfig
lazy val docs = project
.in(file("docs"))
.enablePlugins(SwaggerUiPlugin, SitePlugin)
.settings(
swaggerUiConfig := swaggerUiConfig.value.addUrls(
SwaggerUiConfig.Url.File(
"Petstore Api",
sourceDirectory.value / "main" / "scala" / "docs" / "api" / "petstore.json"
),
SwaggerUiConfig.Url.Remote(
"Github API",
"https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.json"
)
),
makeSite / siteSubdirName := "swagger-ui",
addMappingsToSiteDir(swaggerUiGenerate / mappings, makeSite / siteSubdirName)
)Now if you run sbt docs/makeSite (or sbt docs/previewSite to preview) the swagger-ui site will be added to the sbt-site's output directory.
For example you could link to the swagger-ui site like this:
<html>
<body>
<h1>API</h1>
<p>Please check the swagger-ui documentation <a href="swagger-ui/index.html">here</a>.</p>
</body>
</html>| Name | Type | Description | Default Value |
|---|---|---|---|
| swaggerUiVersion | Setting | The WebJar swagger-ui-dist version to use | 4.1.3 |
| swaggerUiDirectory | Setting | Directory to where swagger-ui-dist files get copied | (Compile / target).value / "sbt-swagger-ui" |
| swaggerUiConfig | Setting | swagger-ui configuration (https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/) | com.fgrutsch.sbt.swaggerui.SwaggerUiConfig.Defaults |
| swaggerUiGenerate | Task | generate swagger-ui site | - |
This code is licensed under the Apache 2.0 License.