OpenAPI generators for Scala 3. Give it an OpenAPI 3.0/3.1 spec and it generates idiomatic Scala 3 models and HTTP routes/controllers.

Small video demo: https://youtu.be/kf0vGrlKNb8

• incremental generator
  • doesn't touch the code that you added manually
  • additive only — adds new properties/methods/classes
• lenient parser + generator
  • if something is not supported it will still (mostly) work
  • you can adapt your OpenAPI spec to work gradually

Openapi4s is a matrix of independent backends — pick one model backend, one framework backend, and optionally a validation backend.

When parsing union types, Tupson tries the members left-to-right and uses the first one that parses. For overlapping object shapes use a discriminator in your oneOf to get a sealed trait instead.

sharaf works with tupson models, http4s works with circe models. Other model/framework combos only print a warning — generated sources may need manual adjustments.

sttp works with both tupson and circe models. tupson clients use ba.sake.sttp.tupson.asJson natively (no generated JsonSupport helper). If you generated with an older version, delete any stale clients/JsonSupport.scala. Generated example:

class PetClient(baseUrl: String) {
  def getPetById(petId: Long): Request[Either[ResponseException[String], Pet]] =
    basicRequest.get(uri"$baseUrl/pet/$petId").response(asJson[Pet])
}

Optionally enable validation of your generated models with --validation:

Incompatible validation/model combos (e.g. --models tupson --validation iron) are rejected at startup.

--models circe --validation iron

Generated models use newtypes such as:

type Email = Email.T
object Email extends RefinedType[String, Match["^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"]]

Add the dependencies that the generated code needs to your own build:

Run the CLI with the Coursier launcher:

cs launch ba.sake::openapi4s-cli:0.7.0 -M ba.sake.openapi4s.cli.OpenApi4sMain -- \
  --models tupson \
  --framework sharaf \
  --validation validson \
  --url openapi.json \
  --baseFolder src/main/scala \
  --basePackage com.example

You can combine the backends independently:

# circe models + http4s routes
--models circe --framework http4s

# tupson models + sharaf controllers
--models tupson --framework sharaf

# models only
--models tupson

# tupson models + sttp client for all tags
--models tupson --client sttp

# circe models + sttp client, only for tags Pet and Store (applies to clients only)
--models circe --client sttp --tags Pet,Store

# models + sharaf server + sttp client in one run
--models tupson --framework sharaf --client sttp

Generated files land in <baseFolder>/<basePackage path>/:

src/main/scala/com/example/
├── models/          # one file per schema (+ Newtypes.scala for iron)
├── controllers/     # sharaf controllers (only with --framework sharaf)
├── routes/          # http4s routes (only with --framework http4s)
└── clients/         # sttp clients (only with --client sttp)

There is also a Mill plugin: https://github.com/sake92/mill-openapi4s

• JSON only — no XML, protobuf, etc.
• http4s backend: routes only; query params and validation are not implemented yet
• sttp client backend: no auth/security schemes, multipart, streaming, or non-JSON content types yet

See DEV.md for development notes and the release process.