Kora Openapi Management

Kora OpenAPI Management

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.

The module contributes plain HttpServerRequestHandler components, so the routes are ordinary public-server routes: global interceptors see them, and the system server (httpServer.system) never serves them. Both viewer pages ship inside the jar with every asset inlined (≈1.9 MB Swagger UI, ≈3.9 MB Scalar) — no CDN call, so they work in an air-gapped network.

Migrating from Kora 1.x — read this first

Every key in the 1.x openapi.management section was renamed, and unknown HOCON keys are ignored without a warning. A copied 1.x block does not "mostly work".

files being mandatory is not a formality: adding OpenApiManagementModule to @KoraApp and configuring nothing at all fails startup, even with enabled = false, because the whole config object is mapped eagerly when the graph is built.

Quick start

1. Dependencies (Java)

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

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")   // koraVersion=2.0.0.RC1
    annotationProcessor "io.koraframework:annotation-processors" // mandatory for @KoraApp

    implementation "io.koraframework:openapi-management"
    implementation "io.koraframework:http-server-undertow"       // required: the module serves over it
    implementation "io.koraframework:config-hocon"
    implementation "io.koraframework:logging-logback"
}

Kotlin replaces the processor with KSP:

implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
ksp("io.koraframework:symbol-processors:${property("koraVersion")}")
implementation("io.koraframework:openapi-management")
implementation("io.koraframework:http-server-undertow")

Java 25 is the floor. Artifacts other than the BOM are never versioned individually, and 2.0.0.RC1 resolves from plain mavenCentral().

2. Application graph

@KoraApp
public interface Application extends
        HoconConfigModule,
        LogbackModule,
        UndertowPublicHttpServerModule,
        OpenApiManagementModule {

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

OpenApiManagementModule only produces request handlers — without an HTTP server module in the graph nothing routes them.

3. Put the spec on the classpath

src/main/resources/
└── openapi/
    ├── api-v1.yaml
    └── api-v2.yaml

files entries are classpath resource paths, not filesystem paths. They are resolved with getResourceAsStream(path) and then getResourceAsStream("/" + path), so openapi/api-v1.yaml and /openapi/api-v1.yaml both work. The file is read lazily on the first request, so a wrong path does not fail startup — it returns 404 OpenAPI file not found while reading: <path>.

4. Configure

Every toggle defaults to false; files has no default at all.

openapi {
  management {
    enabled = true
    files = ["openapi/api-v1.yaml", "openapi/api-v2.yaml"]
    swaggerui {
      enabled = true
    }
    scalar {
      enabled = true
    }
  }
}

Configuration reference — openapi.management

Every key below exists in OpenApiManagementConfig; nothing else in the section is read.

swaggerui.options default:

layout=StandaloneLayout · validatorUrl=null · defaultModelsExpandDepth=0
deepLinking=true · persistAuthorization=true · displayOperationId=true · filter=true

Setting options replaces the whole map — it does not merge. The default is used only when the key is absent, so options { filter = "false" } also drops layout, deepLinking and the rest. Repeat every entry you want to keep. Details and value-literal rules in swagger-ui-reference.md.

The swaggerui key is spelled exactly swaggerui. Kora relaxes key names only across camelCase / kebab-case / snake_case, and swaggerui is a single lowercase token — swaggerUi and swagger-ui do not match it and are silently ignored.

The swaggerui and scalar blocks may be omitted entirely; a missing object maps to an all-defaults instance, which means both viewers are off.

YAML

Same keys, same nesting, via io.koraframework:config-yaml + YamlConfigModule:

openapi:
  management:
    enabled: true
    files:
      - "openapi/api-v1.yaml"
      - "openapi/api-v2.yaml"
    swaggerui:
      enabled: true
    scalar:
      enabled: true

files accepts a list or a comma-separated string

A HOCON array is the clear form, but a plain string is also valid — Kora's collection mapper splits a string value on , and trims each element. Both of these are one file:

files = ["openapi/http-server.yaml"]
files = "openapi/http-server.yaml"

Route layout

The number of entries in files changes the raw-spec route shape.

• One file → GET {path} returns it directly. Default: GET /openapi.
• Several files → the route becomes GET {path}/{file}, where {file} is the resource basename with its directory and its .json / .yml / .yaml suffix stripped. openapi/v1/users-api.yaml ⇒ GET /openapi/users-api.

An unknown {file} returns 404 OpenAPI file not registered: <name>.

Basenames must be unique. The handler indexes the specs by stripped basename, so ["openapi/v1/api.yaml", "openapi/v2/api.yaml"] collapses to a single /openapi/api route serving whichever entry was registered last, and both viewer entries point at it. Name the files api-v1.yaml / api-v2.yaml instead.

Content-Type follows the extension: text/json; charset=utf-8 for .json, otherwise text/x-yaml; charset=utf-8.

Caching

The raw-spec and viewer responses go through the module's own small response cache. Every response carries Vary: Accept-Encoding. When the request advertises Accept-Encoding: gzip (and not gzip;q=0), the body is gzipped and Content-Encoding: gzip is set.

"Content" is the spec resource for /openapi and the rendered page for the viewers. Anything cached lives for the life of the process, so an updated spec needs a restart. NONE is the option to pick if you want the resource re-read every time; it costs a full gzip pass per request.

The three values are matched case-sensitively against the enum constants — NONE, GZIP, FULL. gzip raises ConfigValueException: Unknown enum value: gzip when expected one of […].

Securing the documentation routes

Two options, in order of preference.

1. Turn it off where it does not belong. openapi.management.swaggerui.enabled = false (and scalar.enabled = false) in the production override leaves the raw spec available to tooling while removing the interactive viewers. Setting enabled = false as well removes the spec too.
2. Gate it with a global interceptor. The handlers come from the module, not from your code, so there is nothing to annotate with @InterceptWith. Register one HttpServerInterceptor as a @Component tagged @Tag(HttpServer.class) (io.koraframework.http.server.common.HttpServer), check request.path() against the docs prefixes and call chain.process(request) for everything else. Ready-to-copy templates: assets/SwaggerUiSecurityInterceptor.java.template, assets/SwaggerUiSecurityInterceptor.kt.template.

@Tag(HttpServerModule.class) from 1.x still compiles and the gate silently never runs. Cover it with a test that asserts an unauthenticated GET /swagger-ui is rejected.

Contract-first: publish the spec you generate from

Keep the spec under src/main/resources/openapi/ and point both the generator and the management module at the same file — it is already on the classpath, so no copy task is needed and the published document cannot drift from the generated transport layer.

inputSpec = layout.projectDirectory.file("src/main/resources/openapi/http-server.yaml")

openapi.management.files = ["openapi/http-server.yaml"]

Generation options belong to kora-openapi-generator-server.

Troubleshooting

References

Assets

Related skills

• kora-openapi-generator-server — generate server delegates from a spec
• kora-openapi-generator-client — generate typed HTTP clients
• kora-http-server — server config, ports, interceptors
• kora-http-server-auth — principal extraction for the API itself