The generator can be used in projects with following scala versions: 2.12, 2.13 and 3.x
I decided to archive this project. I kept putting off the rewrite of its internals to make the parser more robust but I think that it will never happen. I no longer have the energy nor the ambition to keep this project alive. Also, nowadays there are better alternatives to describe a service interface (e.g. smithy or protobufs).
If you came here looking for a solution to generate scala code from some description of your api/interface I can recommend following options:
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 (https://github.com/OpenAPITools/openapi-generator/issues/6685). I think that, by extracting and focusing only on a scala related part, it can be done better.
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
)
)
)
}
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
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 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
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
- size
type: object
properties:
name:
type: string
size:
type: integer
sealed trait Entity
case class Organization(size: Int) 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)
}
}
}
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]
)
)
)
}
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]
)
Apart from official openApi generator which was mentioned in the Why? section there are other similar projects.
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.
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.
Push a new tag to the master branch.