Awesome

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.

Quickstart with sbt

Add one of the following dependencies:

// common model classes, including Schema
"com.softwaremill.sttp.apispec" %% "apispec-model" % "0.11.3"

// only model classes, root: OpenAPI
"com.softwaremill.sttp.apispec" %% "openapi-model" % "0.11.3"
// circe encoders for the model classes
"com.softwaremill.sttp.apispec" %% "openapi-circe" % "0.11.3"
// extension method for OpenAPI to convert to yaml
"com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "0.11.3"

// only model classes, root: AsyncAPI
"com.softwaremill.sttp.apispec" %% "asyncapi-model" % "0.11.3"
// circe encoders for the model classes
"com.softwaremill.sttp.apispec" %% "asyncapi-circe" % "0.11.3"
// extension method for AsyncAPI to convert to yaml
"com.softwaremill.sttp.apispec" %% "asyncapi-circe-yaml" % "0.11.3"

sttp apispec is available for Scala 2.12, 2.13, 3, Scala.JS and Scala Native.

Documentation

Javadocs

Usage

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:

Open API

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.11.3"
"com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "0.11.3"

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 model

Encode 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 string

Async API

Currently, AsyncAPI version 2.0 is supported. Usage is the following:

Add dependencies

"com.softwaremill.sttp.apispec" %% "asyncapi-model" % "0.11.3"
"com.softwaremill.sttp.apispec" %% "asyncapi-circe-yaml" % "0.11.3"

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 model

Encode 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 string

Contributing

If 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.

Building & testing the scala-native version

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.

Commercial Support

We offer commercial support for sttp and related technologies, as well as development services. Contact us to learn more about our offer!