The Fabrikt Gradle Plugin integrates Fabrikt into your Gradle builds. Fabrikt generates Kotlin code from an OpenAPI 3 specification. It supports data classes with advanced features, Spring or Micronaut controllers, Ktor route handlers, and OkHttp or OpenFeign clients.
This plugin can be permanently integrated into your Gradle build and will ensure contract and code always match, even as your APIs evolve in complexity.
The plugin requires at least Gradle 9.0 and a JRE 21. If you are using Gradle 8.x, you can use version 1.18.0 of the plugin.
To use it with the Kotlin DSL (build.gradle.kts):
plugins {
id("ch.acanda.gradle.fabrikt") version "1.36.0"
}
fabrikt {
generate("dog") {
apiFile = file("src/main/openapi/dog.yaml")
basePackage = "com.example.api"
}
}To use it with the Groovy DSL (build.gradle):
plugins {
id 'ch.acanda.gradle.fabrikt' version '1.36.0'
}
fabrikt {
dog {
apiFile = file('src/main/openapi/dog.yaml')
basePackage = 'com.example.api'
}
}Note: some configuration options are reserved words or type names that are imported by Groovy by default, so you have to prefix them with
owner..typeOverrides { binary = owner.InputStream owner.'byte' = owner.String datetime = owner.Instant }
When running gradle fabriktGenerate, the examples above will generate the
model classes from the OpenAPI specification in src/main/openapi/dog.yaml. The
model classes will be generated in
build/generated/sources/fabrikt/src/main/kotlin/.
The plugin provides the following tasks:
fabriktGenerate: generates code for all configurations, unless they haveskipset totrue.fabriktGenerate[Name]: generates code for the configuration with the specified name. The suffix[Name]is derived from the configuration´s name by removing non-alphanumeric characters and converting the rest to CamelCase. E.g. the code for the configurationgenerate("dog-api") { ... }can be generated withgradle fabriktGenerateDogApi.
plugins {
id("ch.acanda.gradle.fabrikt") version "1.36.0"
// If you are using IntelliJ IDEA, the plugin will automatically add the
// output directory as a generated sources directory.
idea
}
fabrikt {
generate("dog") {
// mandatory properties
apiFile = file("src/main/openapi/dog.yaml")
basePackage = "com.example.dog.api"
// optional properties with their default values
apiFragments = files()
externalReferenceResolution = targeted
outputDirectory = file("build/generated/sources/fabrikt")
sourcesPath = "src/main/kotlin"
resourcesPath = "src/main/resources"
validationLibrary = Javax
quarkusReflectionConfig = enabled
addFileDisclaimer = disabled
typeOverrides {
datetime = OffsetDateTime
byte = ByteArray
binary = ByteArray
uri = URI
uuid = UUID
date = LocalDate
}
client {
generate = disabled
target = OkHttp
resilience4j = disabled
suspendModifier = disabled
springResponseEntityWrapper = disabled
springCloudOpenFeignStarterAnnotation = disabled
groupByTag = disabled
openFeignClientName = "fabrikt-client"
}
controller {
generate = disabled
authentication = disabled
groupByTag = disabled
suspendModifier = disabled
completionStage = disabled
target = Spring
}
model {
generate = enabled
extensibleEnums = disabled
javaSerialization = disabled
quarkusReflection = disabled
micronautIntrospection = disabled
micronautReflection = disabled
micronautSerdeable = disabled
includeCompanionObject = disabled
sealedInterfacesForOneOf = disabled
faultTolerantEnums = disabled
ignoreUnknownProperties = disabled
serializationLibrary = Jackson
jacksonNullabilityMode = None
instantLibrary = Kotlinx
}
skip = false
}
}| Property | Description | Default value |
|---|---|---|
| apiFile | The path to an Open API v3 specification, interpreted relative to the project directory. | |
| apiFragments | A set of paths to Open API v3 specification fragments, interpreted relative to the project directory. | files() |
| externalReferenceResolution | Specify to which degree referenced schemas from external files are included in model generation. targeted generates models only for directly referenced schemas in external API files. aggressive triggers generation of every external schema in a file containing a referenced schema.Values: targeted, aggressive. |
targeted |
| basePackage | The base package under which all code is built. | |
| outputDirectory | The directory to which the generated classes are written, interpreted relative to the project directory. | build/generated/sources/fabrikt |
| sourcesPath | The path for generated source files, interpreted relative to the output directory. | src/main/kotlin |
| resourcesPath | The path for generated resource files, interpreted relative to the output directory. | src/main/resources |
| typeOverrides.datetime | Specifies the Kotlin type for the OAS type datetime.Values: OffsetDateTime, Instant, LocalDateTime. |
OffsetDateTime |
| typeOverrides.byte | Specifies the Kotlin type for the OAS type string with format byte.Values: ByteArray, String. |
ByteArray |
| typeOverrides.binary | Specifies the Kotlin type for the OAS type string with format binary.Values: ByteArray, InputStream, String. |
ByteArray |
| typeOverrides.uri | Specifies the Kotlin type for the OAS type string with format uri.Values: URI, String. |
URI |
| typeOverrides.uuid | Specifies the Kotlin type for the OAS type string with format uuid.Values: UUID, String. |
UUID |
| typeOverrides.date | Specifies the Kotlin type for the OAS type string with format date.Values: LocalDate, String. |
LocalDate |
| validationLibrary | Specifies the validation library used for annotations in generated model classes. Values: Javax, Jakarta, NoValidation. |
Jakarta |
| quarkusReflectionConfig | Enables generating the reflection-config.json file for quarkus integration projects. Values: enabled, disabled, true, false. |
enabled |
| addFileDisclaimer | Enables adding a disclaimer to the generated files. Values: enabled, disabled, true, false. |
disabled |
| client.generate | Enables generating the http client code. Values: enabled, disabled, true, false. |
disabled |
| client.target | The type of client you want to be generated.OkHttp, OpenFeign, SpringHttpInterface, Ktor. |
OkHttp |
| client.resilience4j | Generates a fault tolerance service for the client using the following library "io.github.resilience4j:resilience4j-all:+". Only for OkHttp clients. Values: enabled, disabled, true, false. |
disabled |
| client.suspendModifier | Enables adding the suspend modifier to the generated client functions. Only for OpenFeign clients. Values: enabled, disabled, true, false. |
disabled |
| client.springResponseEntityWrapper | Enables adding the Spring-ResponseEntity generic around the response to be able to get response headers and status (only for target OpenFeign).Values: enabled, disabled, true, false. |
disabled |
| client.springCloudOpenFeignStarterAnnotation | Enables adding the the @FeignClient annotation to generated client interface (only for target OpenFeign).Values: enabled, disabled, true, false. |
disabled |
| client.groupByTag | Enables grouping clients based on the first tag rather than paths. Values: enabled, disabled, true, false. |
disabled |
| client.openFeignClientName | Specifies the OpenFeign client name for spring-cloud-starter-openfeign (only for target OpenFeign). |
fabrikt-client |
| controller.generate | Enables generating the http controller code. Values: enabled, disabled, true, false. |
disabled |
| controller.authentication | Enables adding the authentication parameter to the generated controller functions. Values: enabled, disabled, true, false. |
disabled |
| controller.groupByTag | Enables grouping controllers based on the first tag rather than paths. Values: enabled, disabled, true, false. |
disabled |
| controller.suspendModifier | Enables adding the suspend modifier to the generated controller functions. Values: enabled, disabled, true, false. |
disabled |
| controller.completionStage | Enables the generated controller functions to have type CompletionStage (only for target Spring).Values: enabled, disabled, true, false. |
disabled |
| controller.target | The target framework tor the controllers you want to be generated. Values: Spring, Micronaut, Ktor. |
Spring |
| model.generate | Enables generating the http model code. Values: enabled, disabled, true, false. |
enabled |
| model.extensibleEnums | Enables treating x-extensible-enums as enums. Values: enabled, disabled, true, false. |
disabled |
| model.javaSerialization | Enables adding the Java Serializable interface to the generated models.Values: enabled, disabled, true, false. |
disabled |
| model.quarkusReflection | Enables adding @RegisterForReflection to the generated models.Requires the dependency io.quarkus:quarkus-core:+.Values: enabled, disabled, true, false. |
disabled |
| model.micronautIntrospection | Enables adding @Introspected to the generated models.Requires the dependency io.micronaut:micronaut-core:+.Values: enabled, disabled, true, false. |
disabled |
| model.micronautReflection | Enables adding @ReflectiveAccess to the generated models.Requires the dependency io.micronaut:micronaut-core:+.Values: enabled, disabled, true, false. |
disabled |
| model.micronautSerdeable | Enables adding @Serdeable to the generated models.Requires the dependency io.micronaut.serde:micronaut-serde-jackson:+.Values: enabled, disabled, true, false. |
disabled |
| model.includeCompanionObject | Enables adding a companion object to the generated models. Values: enabled, disabled, true, false. |
disabled |
| model.sealedInterfacesForOneOf | Enables the generation of sealed interfaces for discriminated oneOf types.Values: enabled, disabled, true, false. |
disabled |
| model.nonNullMapValues | This option makes map values non-null when enabled. The default is to make map values nullable. Values: enabled, disabled, true, false. |
disabled |
| model.faultTolerantEnums | Enables adding an UNRECOGNIZED enum entry as a fallback for unmapped values, preventing deserialization exceptions.Values: enabled, disabled, true, false. |
disabled |
| model.ignoreUnknownProperties | Enables adding @JacksonIgnoreProperties(ignoreUnknown = true) to the generated models.Values: enabled, disabled, true, false. |
disabled |
| model.suffix | Specifies a custom suffix for all generated model classes. | null (no suffix) |
| model.serializationLibrary | Specifies the serialization library to use for annotations in generated model classes. Values: Jackson, Kotlinx. |
Jackson |
| model.jacksonNullabilityMode | Specifies the handling of null values when serializing with Jackson. Values: None, EnforceOptionalNonNull, EnforceRequiredNullable, Strict. |
None |
| model.instantLibrary | Specifies the Instant library to use in generated model classes when using the Kotlinx serialization library.Values: Kotlinx, Kotlin. |
Kotlinx |
| skip | Skips generating code if set to true when running the task fabriktGenerate. Tasks generating code for a single configuration, i.e. fabriktGenerate[Name], ignore this setting.Values: true, false. |
false |
If you have many OpenAPI specifications with nearly the same configuration, you
can set the common values in the defaults. All properties except apiFile and
basePackage can be configured with default values.
Note: The
defaultsblock is only supported in the Kotlin DSL and not in the Groovy DSL.
fabrikt {
defaults {
client {
generate = true
target = OpenFeign
}
}
generate("dog") {
apiFile = file("src/main/openapi/dog.yaml")
basePackage = "com.example.dog.api"
}
generate("cat") {
apiFile = file("src/main/openapi/cat.yaml")
basePackage = "com.example.cat.api"
}
}The above example generates OpenFeign clients for both the dog and cat specifications.
You can use gradle publishToMavenLocal to install the plugin to your local
Maven repository. Then add the local maven repository to settings.gradle.kts of
the project where you want to use the plugin:
pluginManagement {
repositories {
mavenLocal()
// other repositories go here
}
}Validate the plugin:
gradle publishPlugins --validate-onlyPublish the plugin:
gradle publishPlugins \
-Pgradle.publish.key=... \
-Pgradle.publish.secret=... \
-Psigning.gnupg.keyName=...