sttp-openapi-generator

This project is in a very early stage, use it at your own risk!

The generator can be used in projects with following scala versions: 2.12, 2.13 and 3.x

Why?

Why creating another openapi-generator when there is an official one? While the mentioned generator is generally a great project and serves well for many people its scala part has a few flaws in my opinion. There is no proper encoding for discriminators, neither support for other json libraries. The genereted code doesn't feel like native. These, as well as the other things, could (and probably will at some point) be implemented, but the size of the project and underlying templating engine(mustache) don't make it easier. Last but not least it is currently impossible to generate openapi code into src-managed directory (OpenAPITools/openapi-generator#6685). I think that, by extracting and focusing only on a scala related part, it can be done better.

Goals of the project

generate idiomatic scala code
support popular json libararies from scala ecosystem
support only sttp but do it well
proper integration with sbt and other build tools
support discriminators
support error encoding
support open products
comparison to similar projects

Teaser

Given following yaml:

openapi: 3.0.3
info:
  title: Entities
  version: "1.0"
paths:
  /:
    get:
      operationId: getRoot
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
components:
  schemas:
    Person:
      required:
        - name
        - age
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
          minimum: 11

it will be turned into:

trait CirceCodecs extends SttpCirceApi {
  implicit lazy val personDecoder: Decoder[Person] =
    Decoder.forProduct2("name", "age")(Person.apply)
  implicit lazy val personEncoder: Encoder[Person] =
    Encoder.forProduct2("name", "age")(p => (p.name, p.age))
}
object CirceCodecs extends CirceCodecs

case class Person(name: String, age: Int)

class DefaultApi(baseUrl: String, circeCodecs: CirceCodecs = CirceCodecs) {
  import circeCodecs._

  def getRoot(): Request[Person, Any] = basicRequest
    .get(uri"$baseUrl")
    .response(
      fromMetadata(
        asJson[Person].getRight,
        ConditionalResponseAs(
          _.code == StatusCode.unsafeApply(200),
          asJson[Person].getRight
        )
      )
    )
}

Getting started

sbt-plugin

You can use sttp-openapi-codegen seamlessly with sbt via a dedicated sbt plugin. In order to use it, follow the usual convention, first add it to project/plugins.sbt:

addSbtPlugin("io.github.ghostbuster91.sttp-openapi" % "sbt-codegen-plugin" % <version>)

next, enable it for the desired modules in build.sbt:

import SttpOpenApiCodegenPlugin._
enablePlugins(SttpOpenApiCodegenPlugin)

Generator will walk through all files in input directory and generate for each one respective code into output directory. Package name based on directory structure will be preserved.

Code generation can be configured by one of the following options:

sttpOpenApiOutputPath - Directory for sources generated by sttp-openapi generator (default: target/scala-2.12/src_managed/)
sttpOpenApiInputPath - Input resources for sttp-openapi generator (default: ./resources)
sttpOpenApiJsonLibrary - Json library for sttp-openapi generator to use (currently only Circe)
sttpOpenApiHandleErrors - If true the generator will include error information in types (default: true)

For always up-to-date examples of codegen plugin usage refer to sbt tests: https://github.com/ghostbuster91/sttp-openapi-generator/tree/master/sbt-codegen-plugin/src/sbt-test/codegen/simple

mill-plugin

You can use sttp-openapi-codegen seamlessly with mill via a dedicated mill plugin.

import mill._, mill.scalalib._

import $ivy.`io.github.ghostbuster91.sttp-openapi::mill-codegen-plugin:<version>`
import import io.github.ghostbuster91.sttp.client3.OpenApiCodegenScalaModule

object app extends OpenApiCodegenScalaModule {
  def scalaVersion = "2.13.2"
  def mainClass = Some("com.example.Main")
}

Additional configuration options:

/** Input resources for sttp-openapi generator
  */
def sttpOpenApiInput: T[Seq[Input]] = T {
  Seq(
    Input.dir(millSourcePath / "src" / "main" / "openapi"),
    Input.dir(millSourcePath / "openapi")
  )
}

/** Json library for sttp-openapi generator to use
  */
def sttpOpenApiJsonLibrary: T[JsonLibrary] = T(JsonLibrary.Circe: JsonLibrary)

/** If true the generator will include error information in types
  */
def sttpOpenApiHandleErrors: T[Boolean] = T(true)

/** If true the generator will render model classes only if they are
  * referenced by any of the exiting operations
  */
def sttpOpenApiMinimizeOutput: T[Boolean] = T(true)

/** Additional types mapping configuration
  */
def sttpOpenApiTypesMapping: T[TypesMapping] = T(TypesMapping())

For always up-to-date examples of codegen plugin usage refer to mill plugin integration tests: https://github.com/ghostbuster91/sttp-openapi-generator/tree/master/mill-codegen-plugin-itest

discriminators

In the openapi specification there is a notion of discriminators. These objects are used to distinguishing between polymorphic instances of some type based on a given value.

This project takes advantage of them and generates json configs accordingly.

components:
  schemas:
    Entity:
      oneOf:
        - $ref: "#/components/schemas/Person"
        - $ref: "#/components/schemas/Organization"
      discriminator:
        propertyName: name
        mapping:
          john: "#/components/schemas/Person"
          sml: "#/components/schemas/Organization"
    Person:
      required:
        - name
        - age
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
    Organization:
      required:
        - name
      type: object
      properties:
        name:
          type: string

sealed trait Entity { def name: String }
case class Organization(name: String) extends Entity()
case class Person(name: String, age: Int) extends Entity()

trait CirceCodecs extends SttpCirceApi {
  // codecs for Person and Organization omitted for readability

  implicit lazy val entityDecoder: Decoder[Entity] = new Decoder[Entity]() {
    override def apply(c: HCursor): Result[Entity] = c
      .downField("name")
      .as[String]
      .flatMap({
        case "john" => Decoder[Person].apply(c)
        case "sml"  => Decoder[Organization].apply(c)
        case other =>
          Left(DecodingFailure("Unexpected value for coproduct:" + other, Nil))
      })
  }
  implicit lazy val entityEncoder: Encoder[Entity] = new Encoder[Entity]() {
    override def apply(entity: Entity): Json = entity match {
      case person: Person => Encoder[Person].apply(person)
      case organization: Organization =>
        Encoder[Organization].apply(organization)
    }
  }
}

error encoding

In openapi error responses can be represented equally easily as success ones. That is also the case for the sttp client. If you are not a fan of error handling, you can disable that feature in generator settings.

openapi: 3.0.2
info:
  title: Entities
  version: "1.0"
paths:
  /person:
    put:
      summary: Update an existing person
      description: Update an existing person by Id
      operationId: updatePerson
      responses:
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel2"
components:
  schemas:
    ErrorModel:
      required:
        - msg
      type: object
      properties:
        msg:
          type: string
    ErrorModel2:
      required:
        - msg
      type: object
      properties:
        msg:
          type: string

sealed trait UpdatePersonGenericError
case class ErrorModel(msg: String) extends UpdatePersonGenericError()
case class ErrorModel2(msg: String) extends UpdatePersonGenericError()

class DefaultApi(baseUrl: String, circeCodecs: CirceCodecs = CirceCodecs) {
  import circeCodecs._
 
  def updatePerson(): Request[
    Either[ResponseException[UpdatePersonGenericError, CirceError], Unit],
    Any
  ] = basicRequest
    .put(uri"$baseUrl/person")
    .response(
      fromMetadata(
        asJsonEither[UpdatePersonGenericError, Unit],
        ConditionalResponseAs(
          _.code == StatusCode.unsafeApply(400),
          asJsonEither[ErrorModel, Unit]
        ),
        ConditionalResponseAs(
          _.code == StatusCode.unsafeApply(401),
          asJsonEither[ErrorModel2, Unit]
        )
      )
    )
}

open-product

In openapi specifications data models can be extended by arbitrary properties if needed. To do that one has to specify additionalProperties on particular model. At the same time on the call site special codecs need to be provided to support such types. Luckily, sttp-openapi-generator will handle that as well.

openapi: 3.0.3
info:
  title: Entities
  version: "1.0"
paths:
  /:
    get:
      operationId: getRoot
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
components:
  schemas:
    Person:
      required:
        - name
        - age
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
      additionalProperties: true

trait CirceCodecs extends SttpCirceApi {
  implicit lazy val personDecoder: Decoder[Person] = new Decoder[Person]() {
    override def apply(c: HCursor): Result[Person] =
      for {
        name <- c.downField("name").as[String]
        age <- c.downField("age").as[Int]
        additionalProperties <- c.as[Map[String, Json]]
      } yield Person(
        name,
        age,
        additionalProperties.filterKeys(_ != "name").filterKeys(_ != "age")
      )
  }
  implicit lazy val personEncoder: Encoder[Person] = new Encoder[Person]() {
    override def apply(person: Person): Json = Encoder
      .forProduct2[Person, String, Int]("name", "age")(p => (p.name, p.age))
      .apply(person)
      .deepMerge(
        Encoder[Map[String, Json]].apply(person._additionalProperties)
      )
  }

}

case class Person(
    name: String,
    age: Int,
    _additionalProperties: Map[String, Json]
)

Comparison to similar projects

Apart from official openApi generator which was mentioned in the Why? section there are other similar projects.

Guardrail

Guardrail can generate both client and server code. When it comes to client code generation it is similar to that project, although it supports http4s and akka-http, while this project focuses solely on sttp.

Contributing

Contributions are more than welcome. This is an early stage project which means that everything is subject to change.

See the list of issues and pick one! Or report your own.

If you are having doubts on the why or how something works, don't hesitate to ask a question.

Releasing a new version

Push a new tag to the master branch.

jochumb/sttp-openapi-generator