Generating OpenAPI documentation¶
To use, add the following dependencies:
"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "0.12.9"
"com.softwaremill.sttp.tapir" %% "tapir-openapi-circe-yaml" % "0.12.9"
Tapir contains a case class-based model of the openapi data structures in the openapi/openapi-model
subproject (the
model is independent from all other tapir modules and can be used stand-alone).
An endpoint can be converted to an instance of the model by importing the tapir.docs.openapi._
package and calling
the provided extension method:
import sttp.tapir.openapi.OpenAPI
import sttp.tapir.docs.openapi._
val docs: OpenAPI = booksListing.toOpenAPI("My Bookshop", "1.0")
Such a model can then be refined, by adding details which are not auto-generated. Working with a deeply nested case
class structure such as the OpenAPI
one can be made easier by using a lens library, e.g. Quicklens.
Multiple endpoints can be converted to an OpenAPI
instance by calling the extension method on a list of endpoints:
List(addBook, booksListing, booksListingByGenre).toOpenAPI("My Bookshop", "1.0")
The openapi case classes can then be serialised, either to JSON or YAML using Circe:
import sttp.tapir.openapi.circe.yaml._
println(docs.toYaml)
Options¶
Options can be customised by providing an implicit instance of OpenAPIDocsOptions
, when calling .toOpenAPI
.
operationIdGenerator
: each endpoint corresponds to an operation in the OpenAPI format and should have a unique operation id. By default, thename
of endpoint is used as the operation id, and if this is not available, the operation id is auto-generated by concatenating (using camel-case) the request method and path.linkFromChildToParent
: should child schemas contain a backlink to the parent schema usingallOf
, in addition to the parent enumerating all children usingoneOf
. The default istrue
, but e.g. the Redoc visualisation might require this to befalse
.
Exposing OpenAPI documentation¶
Exposing the OpenAPI documentation can be very application-specific. However, tapir contains modules which contain akka-http/http4s routes for exposing documentation using Swagger UI or Redoc:
"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.12.9"
"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-http4s" % "0.12.9"
"com.softwaremill.sttp.tapir" %% "tapir-redoc-http4s" % "0.12.9"
Note: tapir-swagger-ui-akka-http
transitively pulls some Akka modules in version 2.6. If you want to force
your own Akka version (for example 2.5), use sbt exclusion. Mind the Scala version in artifact name:
"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.12.9" exclude("com.typesafe.akka", "akka-stream_2.12")
Usage example for akka-http:
import sttp.tapir.docs.openapi._
import sttp.tapir.openapi.circe.yaml._
import sttp.tapir.swagger.akkahttp.SwaggerAkka
val docsAsYaml: String = myEndpoints.toOpenAPI("My App", "1.0").toYaml
// add to your akka routes
new SwaggerAkka(docsAsYaml).routes
For http4s, use the SwaggerHttp4s
or RedocHttp4s
classes.