kora-openapi-management

Kora OpenAPI Management

Kora sub-skill — obey the kora-v1 meta rules on every task: R0 ensure .kora-agent/ docs+examples are cloned · R1 read this sub-skill before writing code · R2 Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Focus: Publish OpenAPI documents and serve interactive viewers (Swagger UI, RapiDoc) over the Kora HTTP server using OpenApiManagementModule.

When to Use This Skill

Use when you need to:

• Serve OpenAPI documents at an HTTP endpoint (single file at endpoint, or endpoint/{name} per file when several are listed)
• Enable Swagger UI for interactive API documentation (/swagger-ui)
• Enable RapiDoc as an alternative viewer (/rapidoc)
• Expose multiple specs (v1/v2, public/internal/admin) with a selector
• Control documentation visibility (enabled in dev, disabled or gated in prod)

Not for: Code generation from OpenAPI specs — use kora-openapi-generator-server (server delegates) or kora-openapi-generator-client (typed clients).

The canonical end-to-end walkthrough (generate + publish) is the guide .kora-agent/kora-docs/mkdocs/docs/en/guides/openapi-http-server.md.

---

Quick Start

1. Add Dependencies

All Kora artifacts inherit their version from the kora-parent BOM — never pin a ru.tinkoff.kora:* version directly.

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:$koraVersion")
    annotationProcessor "ru.tinkoff.kora:annotation-processors"

    implementation "ru.tinkoff.kora:openapi-management"
    implementation "ru.tinkoff.kora:http-server-undertow" // required HTTP server
}

(Kotlin: ksp "ru.tinkoff.kora:symbol-processors" instead of annotationProcessor.)

2. Enable the Module

Add OpenApiManagementModule to the @KoraApp graph alongside the HTTP server and config modules.

@KoraApp
public interface Application extends
        HoconConfigModule,
        UndertowHttpServerModule,
        OpenApiManagementModule {

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