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);
    }
}

KoraApplication is imported from ru.tinkoff.kora.application.graph.KoraApplication.

3. Place OpenAPI Specs

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

4. Configure

Every toggle defaults to false, so each one you want must be set explicitly.

openapi {
  management {
    file = ["openapi/api-v1.yaml", "openapi/api-v2.yaml"]
    enabled = true
    endpoint = "/openapi"
    swaggerui {
      enabled = true
      endpoint = "/swagger-ui"
    }
  }
}

Result:

The OpenAPI controllers run on the public HTTP server (httpServer.publicApiHttpPort), not the private/management port.

Configuration Reference

Full Configuration

openapi {
  management {
    file = ["openapi/api-v1.yaml", "openapi/api-v2.yaml"]
    enabled = true                    # serve raw specs (default: false)
    endpoint = "/openapi"             # base path for specs (default: /openapi)

    swaggerui {
      enabled = true                  # Swagger UI (default: false), recommended viewer
      endpoint = "/swagger-ui"        # UI path (default: /swagger-ui)
    }

    rapidoc {
      enabled = false                 # RapiDoc (default: false), limited on complex specs
      endpoint = "/rapidoc"           # UI path (default: /rapidoc)
    }
  }
}

Parameters

Endpoint behavior: single vs multiple files

• Single file in file: GET {endpoint} returns the file content directly.
• Multiple files: endpoint becomes a prefix and each spec is served at {endpoint}/{name}, where {name} is the filename without directories or extension. For someDir/api-v1.yaml the path is {endpoint}/api-v1.

openapi {
  management {
    file = ["openapi/petstore.yaml"]   # single file
    enabled = true
    endpoint = "/api/openapi"
  }
}

Result: GET /api/openapi returns the spec content.

References

Detailed guides in references/:

Best Practices

1. Use Swagger UI — full support for complex specs (discriminators, oneOf/anyOf); prefer it over RapiDoc.
2. Toggles default to false — set enabled, swaggerui.enabled (and rapidoc.enabled) explicitly; nothing is served otherwise.
3. Disable or gate the UI in production — keep specs for tooling, hide or protect the UI:

   # application-prod.conf override
   openapi.management.swaggerui.enabled = false
   

   To keep the UI but require auth, gate it with an HttpServerInterceptor — see swagger-ui-reference.md.
4. Contract-first — generate code and serve the same spec file so docs never drift; the spec is the source of truth.
5. Group related APIs — one file per audience (public/internal/admin), listed in file.
6. Validate specs — run python scripts/validate_openapi.py before deployment.

Troubleshooting

Assets

Templates in assets/ (English comments, BOM-pinned versions):

See assets/ for usage.

Related Skills

• kora-openapi-generator-server — generate server delegates from OpenAPI
• kora-openapi-generator-client — generate typed HTTP clients
• kora-http-server — HTTP server configuration, controllers, interceptors