Fabrikt /ˈfa-brikt/ - Kotlin code from OpenAPI 3

<dependency>
  <groupId>io.fabrikt</groupId>
  <artifactId>fabrikt</artifactId>
</dependency>

java -jar fabrikt.jar \
    --output-directory '/tmp' \
    --base-package 'com.example' \
    --api-file '/path-to-api/open-api.yaml' \
    --targets 'client' \
    --targets 'http_models' \
    --http-client-opts resilience4j

val fabrikt: Configuration by configurations.creating

val generationDir = "$buildDir/generated"
val apiFile = "$buildDir/path-to-api/open-api.yaml"

sourceSets {
    main { java.srcDirs("$generationDir/src/main/kotlin") }
    test { java.srcDirs("$generationDir/src/test/kotlin") }
    ...
}

tasks {   
    ...
    val generateCode by creating(JavaExec::class) {
        inputs.files(apiFile)
        outputs.dir(generationDir)
        outputs.cacheIf { true }
        classpath(fabrikt)
        mainClass.set("io.fabrikt.cli.CodeGen")
        args = listOf(
            "--output-directory", generationDir,
            "--base-package", "com.example",
            "--api-file", apiFile,
            "--targets", "http_models",
            "--targets", "client",
            "--http-client-opts", "resilience4j"
        )
    }
    withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
        kotlinOptions.jvmTarget = "17"
        dependsOn(generateCode)
    }
}

dependencies {
     fabrikt("io.fabrikt:fabrikt:+") // This should be pinned  
     ...
}

plugins {
    // find latest version: https://github.com/acanda/fabrikt-gradle-plugin/releases
    id("ch.acanda.gradle.fabrikt") version "1.33.0"
}

fabrikt {
    generate("dog") {
        apiFile = file("src/main/openapi/dog.yaml")
        basePackage = "com.example.api"
    }
}

The exec-maven-plugin is capable of downloading the Fabrikt library from Maven Central and executing its main method with defined arguments.

Fabrikt is also available as a Docker image, which can be convenient for CI/CD pipelines or environments where you prefer not to install Java directly.

The Docker image can be invoked as follows:

docker run --rm -v $(pwd):/workspace ghcr.io/fabrikt-io/fabrikt:latest \
  --output-directory '.' \
  --base-package 'com.example' \
  --api-file 'openapi.yaml' \
  --targets 'http_models'

The command mounts your current directory to /workspace in the container, where Fabrikt will read the OpenAPI specification and write the generated code.

While inline schemas are perfectly valid they are not supported by Fabrikt in all circumstances. This is especially true for request bodies and non-trivial parameters. Instead, define your schemas in the components section of the OpenAPI spec (components.parameters & components.requestBodies). #20, #187

oneOf along with the flag SEALED_INTERFACES_FOR_ONE_OF will generate polymorphic models with sealed interfaces. The discriminator property is used by Fabrikt to determine the subtypes to be generated.

This section documents the available CLI parameters for controlling what gets generated. This documentation is generated using: ./gradlew printCodeGenUsage

The team that built the first version of this tool initially contributed to the Kotlin code generation ability in OpenApiTools, but reached the limits of what could be achieved with template-based generation. This library leverages the rich OpenAPI 3 model provided by KaiZen-OpenApi-Parser and uses Kotlin Poet to programmatically construct Kotlin classes for maximum flexibility.

This project was started by engineers from Zalando Tech and is battle-tested heavily in production there.

The following example shows how allOf can be used to generate polymorphic Kotlin data classes. It does the following:

• A ChildDefinition schema defines both the discriminator mapping details and the schema for the discriminator property. In this case the discriminator property is an enumeration
• In each child schema, allOf is used to merge the ChildDefinition with the child's custom schema. This guarantees that each child schema inherits the correct discriminator property.
• In the Responses schema a oneOf lists only child schemas. This will be detected by Fabrikt and it will generate the list of parent types: List<ChildDefinition>

NOTE: A new feature has been added that allows Polymorphism to be achieved using only a discriminated oneOf. This feature makes use of Kotlin sealed interface and must be explicitly enabled via --http-model-opts, SEALED_INTERFACES_FOR_ONE_OF

openapi: 3.0.0
components:
  schemas:
    ChildDefinition:
      type: object
      discriminator:
        propertyName: some_enum
        mapping:
          obj_one_only: '#/components/schemas/DiscriminatedChild1'
          obj_two_first: '#/components/schemas/DiscriminatedChild2'
          obj_two_second: '#/components/schemas/DiscriminatedChild2'
          obj_three: '#/components/schemas/discriminated_child_3'
      properties:
        discriminating_property:
          $ref: '#/components/schemas/ChildDiscriminator'

    ChildDiscriminator:
      type: string
      enum:
        - obj_one_only
        - obj_two_first
        - obj_two_second
        - obj_three

    DiscriminatedChild1:
      allOf:
        - $ref: '#/components/schemas/ChildDefinition'
        - type: object
          properties:
            some_prop:
              type: string

    DiscriminatedChild2:
      allOf:
        - $ref: '#/components/schemas/ChildDefinition'
        - type: object
          properties:
            some_prop:
              type: string

    discriminated_child_3:
      allOf:
        - $ref: '#/components/schemas/ChildDefinition'

    Responses:
      type: "object"
      properties:
        entries:
          type: "array"
          items:
            oneOf:
              - $ref: "#/components/schemas/DiscriminatedChild2"
              - $ref: "#/components/schemas/DiscriminatedChild2"
              - $ref: "#/components/schemas/discriminated_child_3"

@JsonTypeInfo(
    use = JsonTypeInfo.Id.NAME,
    include = JsonTypeInfo.As.EXISTING_PROPERTY,
    property = "some_enum",
    visible = true
)
@JsonSubTypes(
    JsonSubTypes.Type(
        value = DiscriminatedChild1::class,
        name =
        "obj_one_only"
    ),
    JsonSubTypes.Type(
        value = DiscriminatedChild2::class,
        name =
        "obj_two_first"
    ),
    JsonSubTypes.Type(
        value = DiscriminatedChild2::class,
        name =
        "obj_two_second"
    ),
    JsonSubTypes.Type(value = DiscriminatedChild3::class, name = "obj_three")
)
sealed class ChildDefinition() {
    abstract val someEnum: ChildDiscriminator
}

enum class ChildDiscriminator(
    @JsonValue
    val value: String
) {
    OBJ_ONE_ONLY("obj_one_only"),

    OBJ_TWO_FIRST("obj_two_first"),

    OBJ_TWO_SECOND("obj_two_second"),

    OBJ_THREE("obj_three");

    companion object {
        private val mapping: Map<String, ChildDiscriminator> =
            values().associateBy(ChildDiscriminator::value)

        fun fromValue(value: String): ChildDiscriminator? = mapping[value]
    }
}

data class DiscriminatedChild1(
    @param:JsonProperty("some_prop")
    @get:JsonProperty("some_prop")
    val someProp: String? = null,
    @get:JsonProperty("some_enum")
    @get:NotNull
    override val someEnum: ChildDiscriminator = ChildDiscriminator.OBJ_ONE_ONLY
) : ChildDefinition()

data class DiscriminatedChild2(
    @get:JsonProperty("some_enum")
    @get:NotNull
    override val someEnum: ChildDiscriminator,
    @param:JsonProperty("some_prop")
    @get:JsonProperty("some_prop")
    val someProp: String? = null
) : ChildDefinition()

data class DiscriminatedChild3(
    @get:JsonProperty("some_enum")
    @get:NotNull
    override val someEnum: ChildDiscriminator = ChildDiscriminator.OBJ_THREE
) : ChildDefinition()

data class Responses(
    @param:JsonProperty("entries")
    @get:JsonProperty("entries")
    @get:Valid
    val entries: List<ChildDefinition>? = null
)

Fabrikt is built with Gradle and requires an initialised git repository. The easiest way to build it is to clone the repo locally before executing the build command:

git clone git@github.com:fabrikt-io/fabrikt.git
cd fabrikt/
./gradlew clean build

A utility function is available in GeneratedCodeAsserter.kt to mass change all of the code generation examples in the test resources folder. This is useful when a global change is made to the code generation logic and all of the examples need to be updated.

1. Go to Release Tab
2. Select Draft a new release.
3. Set tag to a version greater than current using symantic versioning, anticipating whether the changes made could break builds.
4. Click Generate release notes. Ensure that the tag and release version match.
5. Click Publish release buttom at the bottom.

Github Actions will publish the deployment to Sonatype Central. You must then log in to Sonatype and decide to either release or drop that deployment. After 30 minutes or so, Maven Central will have indexed the promoted release.