Kora Openapi Generator Server

Kora OpenAPI Generator — HTTP Server

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Version: Kora 2.0 (io.koraframework, 2.0.0.RC1 on Maven Central) | Java: 25 | Kotlin: 2.4 + KSP | Gradle: 9+

The kora generator turns an OpenAPI 3.x contract into the whole transport layer of a Kora HTTP server. You implement exactly one thing: the generated *ApiDelegate interface, as a @Component. Everything else — routing, parameter binding, JSON, response mapping, security interceptors — is generated and must never be edited or hand-written alongside.

Kora 2.0 contracts are synchronous. Delegate methods return a value directly; there is no Mono, Flux, CompletionStage or suspend variant of a delegate, and Context no longer exists anywhere in the framework.

Only four generator modes exist

configOptions.mode accepts exactly java-client, java-server, kotlin-client, kotlin-server (CodegenMode in the generator). Anything else fails generation with "Invalid OpenAPI generator mode" and a list of the supported values.

Any other reactive/async/suspend variant is equally invalid — the mode string must be one of the four above.

Migrating from Kora 1.x

Two of these fail only at runtime, never at compile time:

• fromValue, not valueOf. The wire value in the contract (available) need not match the generated constant (AVAILABLE). Enum.valueOf("available") throws for perfectly valid input. fromValue throws IllegalArgumentException only for values outside the contract, and the delegate turns that into the contract's 400.
• Security tags are named after the security scheme. components.securitySchemes.BearerAuth becomes the nested marker ApiSecurity.BearerAuth. Ordinal SecurityRequirementTagN names do not exist in 2.0, so an extractor tagged that way is simply never found.

The Gradle process itself must run on JDK 25+

io.koraframework:openapi-generator goes on the buildscript classpath, which is resolved by the JVM running Gradle — not by the project toolchain. A Java 25 toolchain { } block is not enough. On an older Gradle JVM configuration fails with:

Dependency requires at least JVM runtime version 25. This build uses a Java 21 JVM.

Fix it where the Gradle JVM is chosen (JAVA_HOME, org.gradle.java.home, or the IDE's Gradle JVM setting), not in the toolchain block. This is the single most common setup failure here.

Quick Start

1. gradle.properties

2.0.0.RC1 is the Kora 2.0 release on Maven Central and resolves from plain mavenCentral(). 2.0.0-SNAPSHOT is the development line; it needs https://central.sonatype.com/repository/maven-snapshots and does not belong in a new project.

koraVersion=2.0.0.RC1

2. Build wiring

Two independent versions are in play here — do not conflate them:

The Kora generator is built against org.openapitools:openapi-generator 7.24.0 (framework version catalog), and that is the version stamped into .openapi-generator/VERSION in the output, so 7.24.0 is the aligned plugin choice.

===! ":fontawesome-brands-java: Java"

```groovy title="build.gradle"
import org.openapitools.generator.gradle.plugin.tasks.GenerateTask

buildscript {
    repositories { mavenCentral() }
    dependencies {
        classpath("io.koraframework:openapi-generator:$koraVersion")
    }
}

plugins {
    id "java"
    id "application"
    id "org.openapi.generator" version "7.24.0"
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

configurations {
    koraBom
    annotationProcessor.extendsFrom(koraBom)
    compileOnly.extendsFrom(koraBom)
    implementation.extendsFrom(koraBom)
    testImplementation.extendsFrom(koraBom)
}

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")
    annotationProcessor "io.koraframework:annotation-processors"

    implementation "io.koraframework:http-server-undertow"
    implementation "io.koraframework:json-common"
    implementation "io.koraframework:config-hocon"
    implementation "io.koraframework:logging-logback"
    implementation "io.koraframework:validation-module"   // required by enableServerValidation
}
```

=== ":simple-kotlin: Kotlin"

```kotlin title="build.gradle.kts"
import org.openapitools.generator.gradle.plugin.tasks.GenerateTask

buildscript {
    repositories { mavenCentral() }
    dependencies {
        classpath("io.koraframework:openapi-generator:${property("koraVersion")}")
    }
}

plugins {
    id("application")
    kotlin("jvm") version "2.4.10"
    id("com.google.devtools.ksp") version "2.3.11"
    id("org.openapi.generator") version "7.24.0"
}

kotlin {
    jvmToolchain { languageVersion.set(JavaLanguageVersion.of(25)) }
}

dependencies {
    implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
    ksp("io.koraframework:symbol-processors:${property("koraVersion")}")

    implementation("io.koraframework:http-server-undertow")
    implementation("io.koraframework:json-common")
    implementation("io.koraframework:config-hocon")
    implementation("io.koraframework:logging-logback")
    implementation("io.koraframework:validation-module")
}
```

3. Generation task

===! ":fontawesome-brands-java: Java"

```groovy title="build.gradle"
def openApiGenerateHttpServer = tasks.register("openApiGenerateHttpServer", GenerateTask) {
    generatorName = "kora"
    group = "openapi tools"
    inputSpec = layout.projectDirectory.file("src/main/resources/openapi/pet-api.yaml")
    outputDir = layout.buildDirectory.dir("generated/pet-api-server")   // unique per spec
    def corePackage = "com.example.petapi"
    apiPackage = "${corePackage}.api"
    modelPackage = "${corePackage}.model"
    invokerPackage = "${corePackage}.invoker"
    configOptions = [
        mode                  : "java-server",
        enableServerValidation: "true",
    ]
}
sourceSets.main { java.srcDirs += openApiGenerateHttpServer.get().outputDir }
compileJava.dependsOn openApiGenerateHttpServer
```

=== ":simple-kotlin: Kotlin"

```kotlin title="build.gradle.kts"
val openApiGenerateHttpServer = tasks.register<GenerateTask>("openApiGenerateHttpServer") {
    generatorName.set("kora")
    group = "openapi tools"
    inputSpec.set("$projectDir/src/main/resources/openapi/pet-api.yaml")
    outputDir.set(layout.buildDirectory.dir("generated/pet-api-server").get().asFile.absolutePath)
    val corePackage = "com.example.petapi"
    apiPackage.set("$corePackage.api")
    modelPackage.set("$corePackage.model")
    invokerPackage.set("$corePackage.invoker")
    configOptions.set(
        mapOf(
            "mode" to "kotlin-server",
            "enableServerValidation" to "true",
        )
    )
}
kotlin.sourceSets.main { kotlin.srcDir(openApiGenerateHttpServer.get().outputDir) }
tasks.matching { it.name.startsWith("ksp") }.configureEach { dependsOn(openApiGenerateHttpServer) }
tasks.compileKotlin { dependsOn(openApiGenerateHttpServer) }
```

Kotlin needs both hooks: KSP reads the generated sources, and compileKotlin compiles them. Wiring only one of them produces "unresolved reference" errors on a clean build.

4. Plug the modules into @KoraApp

@KoraApp
public interface Application extends
        HoconConfigModule,
        LogbackModule,
        JsonModule,
        ValidationModule,                  // only with enableServerValidation = true
        UndertowPublicHttpServerModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

KoraApplication is io.koraframework.application.graph.KoraApplication.

Do not extends the generated ApiSecurity / *ApiModule interfaces. They carry @Module, and the @KoraApp processor discovers every @Module-annotated interface in the compilation round automatically (KoraAppProcessor#processModules). The migrated examples list only the framework modules.

httpServer {
  port = 8080
  system.port = 8085
  telemetry.logging.enabled = true   # logging and metrics default to false in 2.0
}

5. Implement the generated delegate

For a tag pet the generator emits PetApiDelegate (one method per operationId) and PetApiResponses (one sealed interface per operation, one record per declared status).

===! ":fontawesome-brands-java: Java"

```java
package com.example.petapi.delegate;

import io.koraframework.common.annotation.Component;
import org.jspecify.annotations.Nullable;
import com.example.petapi.api.PetApiDelegate;
import com.example.petapi.api.PetApiResponses;
import com.example.petapi.model.Pet;

@Component
public final class PetDelegate implements PetApiDelegate {

    private final PetService petService;

    public PetDelegate(PetService petService) {
        this.petService = petService;
    }

    @Override
    public PetApiResponses.GetPetByIdApiResponse getPetById(long petId) {
        var pet = petService.find(petId);
        return pet == null
            ? new PetApiResponses.GetPetByIdApiResponse.GetPetById404ApiResponse()
            : new PetApiResponses.GetPetByIdApiResponse.GetPetById200ApiResponse(pet);
    }

    @Override
    public PetApiResponses.FindPetsByStatusApiResponse findPetsByStatus(@Nullable String status) {
        final Pet.StatusEnum parsed;
        try {
            parsed = Pet.StatusEnum.fromValue(status);       // never Enum.valueOf
        } catch (IllegalArgumentException e) {
            return new PetApiResponses.FindPetsByStatusApiResponse.FindPetsByStatus400ApiResponse();
        }
        return new PetApiResponses.FindPetsByStatusApiResponse
            .FindPetsByStatus200ApiResponse(petService.byStatus(parsed));
    }
}
```

=== ":simple-kotlin: Kotlin"

```kotlin
package com.example.petapi.delegate

import io.koraframework.common.annotation.Component
import com.example.petapi.api.PetApiDelegate
import com.example.petapi.api.PetApiResponses
import com.example.petapi.model.Pet

@Component
class PetDelegate(private val petService: PetService) : PetApiDelegate {

    override fun getPetById(petId: Long): PetApiResponses.GetPetByIdApiResponse {
        val pet = petService.find(petId)
            ?: return PetApiResponses.GetPetByIdApiResponse.GetPetById404ApiResponse()
        return PetApiResponses.GetPetByIdApiResponse.GetPetById200ApiResponse(pet)
    }

    override fun findPetsByStatus(status: String?): PetApiResponses.FindPetsByStatusApiResponse {
        val parsed = try {
            status?.let(Pet.StatusEnum::fromValue)
        } catch (_: IllegalArgumentException) {
            null
        } ?: return PetApiResponses.FindPetsByStatusApiResponse.FindPetsByStatus400ApiResponse()

        return PetApiResponses.FindPetsByStatusApiResponse
            .FindPetsByStatus200ApiResponse(petService.byStatus(parsed))
    }
}
```

6. Build and run

./gradlew clean classes   # generate, then compile
./gradlew run

Use clean (and --no-build-cache) on the first build after changing apiPackage, modelPackage or the spec's package layout — see the pitfalls table.

What gets generated

For apiPackage = com.example.petapi.api and a spec tag pet:

Routing is registered by the Kora HTTP-server annotation processor, which generates PetApiControllerModule from the @HttpController. That is a separate step from OpenAPI generation, and it is why the annotation processor / KSP dependency is mandatory.

Core rules

1. Implement *ApiDelegate, nothing else. Never hand-write an @HttpController or @HttpRoute for an operation that the generator already covers — you would register the route twice.
2. Return the generated response record, never a raw DTO. There is no ResponseEntity.
3. A response record exists only for a status declared in the contract. Need a 500? Declare "500" under that operation's responses and regenerate.
4. @Component on the delegate implementation — it is what the compile-time graph resolves into the generated controller's constructor.
5. Parse generated enums with fromValue, and map IllegalArgumentException to the contract's error response.
6. Tag principal extractors with the scheme-named marker, e.g. @Tag(ApiSecurity.BearerAuth.class).
7. Never edit anything under build/generated. A stale-package error is fixed by clean, not by editing output.
8. Kotlin models: use named arguments. Optional properties carry defaults but stay in spec order, so a positional call breaks (or silently shifts) as soon as the contract changes.

Common pitfalls

References

Related skills: kora-http-server, kora-http-server-auth, kora-openapi-generator-client, kora-openapi-management, kora-json, kora-aop-validation.

Upstream: kora @ 2.0.0.RC1, kora-examples @ migration/2.0, OpenAPI Generator Gradle plugin. There is no Kora 2.0 documentation site — kora-docs documents 1.x only.

Assets