Original Motivation

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.

Specific Features

Request and response models

By default, Fabrikt generates one model set and treats readOnly and writeOnly properties as optional. Directional model generation is opt-in:

• --http-model-opts EXCLUDE_READ_ONLY excludes readOnly properties for a request-model generation pass.
• --http-model-opts EXCLUDE_WRITE_ONLY excludes writeOnly properties for a response-model generation pass.
• --http-model-opts REQUEST_RESPONSE_MODELS generates both model sets in one invocation, with Request and Response appended to model names.

In each directional model set, retained properties follow their declared requiredness and nullability. Filtering applies to properties of every type, including nested models and compositions. Selecting both exclusion options excludes both categories; explicit exclusion options also apply to both sets when combined with REQUEST_RESPONSE_MODELS.

For separate generation passes, use --http-model-suffix Request and --http-model-suffix Response to distinguish the model sets. With REQUEST_RESPONSE_MODELS, a custom suffix precedes the direction suffix, for example PetDtoRequest and PetDtoResponse. Both sets include enums and models without directional properties, keeping all generated references within their respective set. A model whose properties are all excluded becomes an empty Kotlin object.

When REQUEST_RESPONSE_MODELS is enabled, all supported clients and controllers use request models for incoming parameters and request bodies, and response models for returned bodies. Array and map element types follow the same direction. For targets that support multipart, requests omit excluded properties and use request models for structured parts. Existing multipart limitations remain unchanged: Micronaut controllers reject multipart parameters, while Ktor clients and controllers do not generate multipart part parameters. A type referenced by a parameter remains available even if its declaring property is excluded from a model. This option works with HTTP_MODELS, CLIENT, and CONTROLLERS; generating clients or controllers also generates both model sets.

Polymorphism via allOf

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: Discriminated oneOf is the recommended way to model polymorphism. Fabrikt generates a Kotlin sealed interface for every oneOf, so no extra option is needed; the allOf pattern shown here remains supported for existing hierarchies.

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")
    val entries: List<@Valid ChildDefinition>? = null
)

Bean validation

When a validated library is selected, @Valid is placed on the container's type argument for collection properties and controller parameters, e.g. List<@Valid ChildDefinition> and Map<String, @Valid ChildDefinition?>, rather than on the container itself (List<ChildDefinition>). Hibernate Validator 9.1 deprecates the legacy container-level placement.

Nested containers keep @Valid on the innermost element only (e.g. List<List<@Valid ChildDefinition>>), and containers with a non-cascadable element such as List<String> carry no @Valid.

Kotlin only writes type-argument annotations into bytecode when compiled with -Xemit-jvm-type-annotations. Enable that flag in consumer projects so Hibernate Validator can see the cascading @Valid at runtime.

Contributing

Building Locally

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

Adjusting Test Examples

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.

Publishing

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.