ogen is a Gradle plugin that generates Kotlin code from OpenAPI specifications. It is designed to be idiomatic, supporting both Kotlin Multiplatform (KMP) and modern server/client frameworks.
- Type-safe Models: Generates Kotlin data classes and enums with kotlinx.serialization support.
- Shared Models: Core feature allowing models to be generated in a separate Gradle module, shared between server and client.
- Advanced OpenAPI Support: Supports OpenAPI 3.0 and 3.1, including
oneOf(via sealed interfaces),allOf,anyOf, and complex nested schemas. - Kotlin Multiplatform: Seamlessly works with KMP projects, generating code into the appropriate source sets.
- Spring Boot Support: Generates server interfaces for Spring Boot (WebFlux).
- Ktor Client Support: Generates Ktor clients (a Ktor server generator is planned).
- Multipart Requests: Supports
multipart/form-datarequest bodies, including file uploads, in the Spring server and the Ktor client. - OpenAPI Validation: Built-in validator to ensure your OpenAPI specs follow best practices and naming conventions.
- Highly Configurable: Custom type mappings, schema mappings, and naming convention enforcement.
Apply the plugin and add the runtime libraries in your build.gradle.kts:
plugins {
kotlin("jvm") // or kotlin("multiplatform")
kotlin("plugin.serialization")
id("de.quati.ogen") version "0.17.0"
}
dependencies {
implementation("de.quati.ogen:core:0.17.0")
implementation("de.quati.ogen:client-ktor:0.17.0") // Optional: only required for generated Ktor clients
implementation("de.quati.ogen:server-spring:0.17.0") // Optional: only required for the Spring server with `apiResponse = true`
implementation("de.quati:kotlin-util:2.6.1") // Provides `Option`, used by generated models for optional properties
}The generated code also needs kotlinx-serialization-json. If your spec uses format: uuid, the generated code uses
kotlin.uuid.Uuid, which requires opting in to kotlin.uuid.ExperimentalUuidApi:
kotlin {
compilerOptions {
optIn.add("kotlin.uuid.ExperimentalUuidApi")
}
}Configure the generator using the ogen extension. utilPackageName, a spec (specFile or specMerge) and model
are required; everything else is optional.
ogen {
utilPackageName("com.example.api.gen.util")
add(packageName = "com.example.api.gen") {
specFile("$projectDir/specs/api.yaml")
// Optional: Validate the spec; without this block, no validation runs
validator {
failOnWarnings = true
// Enforce naming conventions
propertyNameFormat = NameConvention.CamelCase
schemaNameFormat = NameConvention.PascalCase
}
// Required: Generate models
model {
// Map OpenAPI types to existing Kotlin/Java classes
typeMapping(
type = "string+date-time", clazz = "java.time.OffsetDateTime",
serializerObject = "com.example.serializers.OffsetDateTimeSerializer"
)
// Map specific schemas to existing classes
schemaMapping(schema = "UserId", clazz = "com.example.models.UserId")
}
// Optional: Generate Spring Boot server interfaces
serverSpringV4 {
// Adds an OperationContext parameter (containing meta-info about the endpoint) to each generated function
addOperationContext = true
// Optional: If the operation has any security requirements, add the specified class as a parameter
contextIfAnySecurity("com.example.api.AuthContext")
// Optional: Return typed ApiResponse classes instead of ResponseEntity (requires de.quati.ogen:server-spring)
apiResponse = true
}
// Optional: Generate Ktor Client
clientKtor {}
}
}- Multiple specs: call
addonce per spec, each with its own package name. - Package names and postfixes: by default, models go to
<packageName>.modelwith the postfixDto, the Spring server to<packageName>.serverand the Ktor client to<packageName>.client, both with the postfixApi. Each ofmodel,serverSpringV4andclientKtorcan override this withpackageNameandpostfix. - Type and schema mappings:
typeMappingtakestypeas<type>or<type>+<format>(e.g.string+date-time).schemaMappingtakes a schema name; nested schemas are separated by dots.serializerObjectis optional for both. - Merging specs: instead of
specFile,specMerge(path = "$projectDir/specs")merges all specs in a directory. The merged spec'sinfois set withmergedFileInfoTitle,mergedFileInfoVersionandmergedFileInfoDescription, or taken from a base spec withspecMerge(path = ..., baseSpec = "$projectDir/specs/base.yaml"). - Operation IDs: for operations without an
operationId,operationIdGenerator { info -> ... }derives one from anEndpointInfo(tag,path,relativePath,method). If it returnsnullor isn't set, the name is derived from the path and method. - Validation rules: besides
failOnWarnings(defaultfalse) andrecommendations(defaulttrue), thevalidatorblock sets naming conventions forschemaNameFormat(defaultPascalCase),propertyNameFormat,tagFormatandoperationIdFormat(defaultCamelCase),pathSegmentFormat(defaultKebabCase),stringEnumFormat(defaultAny) and, viaparameterFormat { path; query; header; cookie }, parameter names. Besides the predefined conventions,NameConvention.RegexFormat("...")andNameConvention.Custom { name -> ... }define custom ones. The conventions apply to every schema and parameter the generator sees, inline request and response schemas, composition members and path-level parameters included. - What the validator checks: swagger-parser's errors, the naming conventions and these checks fail the build: broken
path templates (an empty
{}, an unclosed{or a stray}), a query string or fragment in a path key, path parameters missing from the path template, paths that differ only in their variables' names, security schemes not defined incomponents.securitySchemes, atypethat isn't a JSON Schema type, enum values that don't match their schema's type or are listed twice, adefaultitsenumdoesn't list,requirednames without a matching property, contradictory constraints such asminimumabovemaximum, and compositions no value can match:allOfmembers whose types exclude each other or the schema's own type, or a type that excludes everyoneOforanyOfmember. These are warnings: paths with a trailing slash, operations without a 2xx or 3xx response, operation tags missing from the top-leveltags(when it declares any),nullablewithout atypein OpenAPI 3.0,patternregexes andpatternPropertieskeys that don't compile as Java regexes (OpenAPI's are JavaScript's, which differ slightly), keywords that apply to none of the schema's declared types, such asmaxLengthon an integer, in OpenAPI 3.1maximumnext toexclusiveMaximumorminimumnext toexclusiveMinimum, where only the tighter bound has an effect, and ambiguous paths: two paths that share a method where neither is more concrete (/{entity}/meand/books/{id}). openapi-generator's recommendations are warnings too;recommendations = falseturns off only those.failOnWarnings = truefails the build on any warning.
When using contextIfAnySecurity, you must provide a custom HandlerMethodArgumentResolver to Spring Boot so it knows how to inject your context class into the controller methods.
Example registration in a WebFluxConfigurer:
@Configuration
class WebConfig : WebFluxConfigurer {
override fun configureArgumentResolvers(configurer: ArgumentResolverConfigurer) {
configurer.addCustomResolver(AuthContext.ArgumentResolver)
}
}With apiResponse = true, every controller function returns a generated response type implementing
de.quati.ogen.server.spring.ApiResponse instead of a ResponseEntity. If an operation defines multiple responses,
a sealed interface with one class per response is generated; for a single response it is a single class. Response
classes are data classes, except for streamed (Flow) and untyped (e.g. binary) bodies, which only have identity
equality.
Every response class accepts optional headers; status ranges (5XX) and default responses take the status as
parameter. Responses with a body also carry their content types from the spec, which are used for the
content negotiation instead of the produces of the request mapping, so error responses can use a different content
type (e.g. application/json) than the success response (e.g. image/png).
suspend fun getUser(userId: String): GetUserResponse
sealed interface GetUserResponse : ApiResponse {
data class Ok(override val body: UserDto, override val headers: HttpHeaders = HttpHeaders.EMPTY) : GetUserResponse {
override val status: HttpStatusCode = HttpStatus.OK
}
data class Unauthorized(override val headers: HttpHeaders = HttpHeaders.EMPTY) : GetUserResponse {
override val status: HttpStatusCode = HttpStatus.UNAUTHORIZED
}
data class NotFound(override val body: ErrorDto, override val headers: HttpHeaders = HttpHeaders.EMPTY) : GetUserResponse {
override val status: HttpStatusCode = HttpStatus.NOT_FOUND
}
}The responses are written by ApiResponseResultHandler (a WebFlux HandlerResultHandler) from server-spring, which
is registered by Spring Boot auto-configuration in reactive web applications. To customize it, define your own
ApiResponseResultHandler bean; without Spring Boot, register it manually.
The plugin registers the following tasks:
ogenGenerate: Generates Kotlin code from the configured OpenAPI specifications intobuild/generated/sources/ogen, validating them first if avalidatoris configured. This task is automatically hooked into the Kotlin compilation process. It runs on every build and is not compatible with the configuration cache.ogenValidate: Validates the OpenAPI specifications against the configured rules without generating code.
- JDK 21 or higher
- Kotlin 2.2 or higher
This project is licensed under the MIT License.