Generating AsyncAPI documentation¶
To use, add the following dependencies:
"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "0.17.0-M8" "com.softwaremill.sttp.tapir" %% "tapir-asyncapi-circe-yaml" % "0.17.0-M8"
Tapir contains a case class-based model of the asyncapi data structures in the
asyncapi/asyncapi-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
sttp.tapir.docs.asyncapi._ package and calling
the provided extension method:
import sttp.capabilities.akka.AkkaStreams import sttp.tapir._ import sttp.tapir.asyncapi.AsyncAPI import sttp.tapir.docs.asyncapi._ import sttp.tapir.json.circe._ import io.circe.generic.auto._ case class Response(msg: String, count: Int) val echoWS = endpoint.out( webSocketBody[String, CodecFormat.TextPlain, Response, CodecFormat.Json](AkkaStreams)) val docs: AsyncAPI = echoWS.toAsyncAPI("Echo web socket", "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
AsyncAPI one can be made easier by using a lens library, e.g. Quicklens.
Quite often, you’ll need to define the servers, through which the API can be reached. Any servers provided to the
.toAsyncAPI invocation will be supplemented with security requirements, as specified by the endpoints:
import sttp.tapir.asyncapi.Server val docsWithServers: AsyncAPI = echoWS.toAsyncAPI( "Echo web socket", "1.0", List("production" -> Server("api.example.com", "wss")) )
Servers can also be later added through methods on the
Multiple endpoints can be converted to an
AsyncAPI instance by calling the extension method on a list of endpoints/
The asyncapi case classes can then be serialised, either to JSON or YAML using Circe:
import sttp.tapir.asyncapi.circe.yaml._ println(docs.toYaml)
Options can be customised by providing an implicit instance of
AsyncAPIDocsOptions, when calling
subscribeOperationId: basing on the endpoint’s path and the entire endpoint, determines the id of the subscribe operation. This can be later used by code generators as the name of the method to receive messages from the socket.
publishOperationId: as above, but for publishing (sending messages to the web socket).