sttp is a family of Scala HTTP-related projects, and currently includes:
- sttp client: The Scala HTTP client you always wanted!
- sttp tapir: Typed API descRiptions.
- sttp model: Simple Scala HTTP model.
- sttp apispec: this project. OpenAPI, AsyncAPI and JSON Schema models.
Add one of the following dependencies:
// common model classes, including Schema
"com.softwaremill.sttp.apispec" %% "apispec-model" % "0.10.0"
// only model classes, root: OpenAPI
"com.softwaremill.sttp.apispec" %% "openapi-model" % "0.10.0"
// circe encoders for the model classes
"com.softwaremill.sttp.apispec" %% "openapi-circe" % "0.10.0"
// extension method for OpenAPI to convert to yaml
"com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "0.10.0"
// only model classes, root: AsyncAPI
"com.softwaremill.sttp.apispec" %% "asyncapi-model" % "0.10.0"
// circe encoders for the model classes
"com.softwaremill.sttp.apispec" %% "asyncapi-circe" % "0.10.0"
// extension method for AsyncAPI to convert to yaml
"com.softwaremill.sttp.apispec" %% "asyncapi-circe-yaml" % "0.10.0"sttp apispec is available for Scala 2.12, 2.13, 3, Scala.JS and Scala Native.
Sttp-apispec defines models and encoding/decoding logic for OpenAPI / AsyncAPI documentation. While for the most part sttp-apispec is meant to be used with tapir (where tapir converts endpoint definitions to OpenAPI/AsyncAPI model, and then sttp-apispec encodes it to desired documentation file) it can be used as a stand-alone as well in the following way:
Currently, OpenAPI versions 3.0.3 and 3.1 are supported, where the models are the same, and choosing one version over the other is a matter of selecting the proper encoder.
Add dependencies:
"com.softwaremill.sttp.apispec" %% "openapi-model" % "0.10.0"
"com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "0.10.0"Create example OpenAPI models:
import sttp.apispec.openapi._
import scala.collection.immutable.ListMap
val openApi3_1_0 = OpenAPI(
openapi = "3.1.0",
info = Info(title = "Fruits", version = "1.0"),
paths = Paths(ListMap("/" ->
PathItem(get = Some(Operation(
operationId = Some("getRoot"),
responses = Responses(ListMap(ResponsesCodeKey(200) -> Right(Response(description = "")))))))))
) // define example OpenAPI 3.1.0 model
val openApi3_0_3 = openApi3_1_0.openapi("3.0.3") // and example OpenAPI 3.0.3 modelEncode it to the Open API YAML string:
import sttp.apispec.openapi.circe.yaml._
val yaml3_1_0 = openApi3_1_0.toYaml // converts model to OpenApi 3.1.0 yaml string
val yaml3_0_3 = openApi3_0_3.toYaml3_0_3 // converts model to OpenApi 3.0.3 yaml stringCurrently, AsyncAPI version 2.0 is supported. Usage is the following:
Add dependencies
"com.softwaremill.sttp.apispec" %% "asyncapi-model" % "0.10.0"
"com.softwaremill.sttp.apispec" %% "asyncapi-circe-yaml" % "0.10.0"Create an example AsyncAPI model:
import sttp.apispec.asyncapi._
import sttp.apispec.{Schema, SchemaType}
import scala.collection.immutable.ListMap
val asyncApi = AsyncAPI(
asyncapi = "2.0.0",
id = None,
info = Info(title = "Fruits", version = "1.0"),
servers = ListMap.empty,
channels = ListMap("/" -> Right(ChannelItem(
description = None,
subscribe = Some(Operation(
operationId = Some("onRoot"),
summary = None,
description = None,
tags = List.empty,
externalDocs = None,
bindings = List.empty,
traits = List.empty,
message = Some(Right(SingleMessage(payload = Some(Right(Right(Schema(SchemaType.Integer))))))),
)),
publish = None,
parameters = ListMap.empty,
bindings = List.empty
))),
components = None,
tags = List.empty,
externalDocs = None
) //define example AsyncApi 2.0.0 modelEncode it to Async API YAML string:
import sttp.apispec.asyncapi.circe.yaml._
val yaml2_0 = asyncApi.toYaml // // convert model to AsyncApi 2.0.0 yaml stringIf you have a question, or hit a problem, feel free to ask on our gitter channel!
Or, if you encounter a bug, something is unclear in the code or documentation, don’t hesitate and open an issue on GitHub.
By default, native projects will not be included in the aggregate build of the root project. To include it, define the STTP_NATIVE environmental variable before running sbt, e.g.:
STTP_NATIVE=1 sbt
You might need to install some additional libraries, see the scala native documentation site.
We offer commercial support for sttp and related technologies, as well as development services. Contact us to learn more about our offer!
Copyright (C) 2022 SoftwareMill https://softwaremill.com.
