OpenAPI

Ktor allows you to serve OpenAPI documentation based on an OpenAPI specification.

You can provide the OpenAPI specification in one of the following ways:

Serve an existing YAML or JSON file.
Generate the specification at runtime using the OpenAPI compiler extension and runtime APIs.

In both cases, the OpenAPI plugin assembles the specification on the server and renders the documentation as HTML.

Add dependencies

Serving OpenAPI documentation requires adding the ktor-server-openapi artifact in the build script:
implementation("io.ktor:ktor-server-openapi:$ktor_version")
implementation "io.ktor:ktor-server-openapi:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-openapi-jvm</artifactId> <version>${ktor_version}</version> </dependency>
Optionally, add the swagger-codegen-generators dependency if you want to customize a code generator:
implementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")
implementation "io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version"
<dependency> <groupId>io.swagger.codegen.v3</groupId> <artifactId>swagger-codegen-generators</artifactId> <version>${swagger_codegen_version}</version> </dependency>
You can replace $swagger_codegen_version with the required version of the swagger-codegen-generators artifact, for example, 1.0.36.

Use a static OpenAPI file

To serve OpenAPI documentation from an existing specification, use the openAPI() function with a provided path to the OpenAPI document.

The following example creates a GET endpoint at the openapi path and renders the Swagger UI from the provided OpenAPI specification file:

import io.ktor.server.plugins.openapi.*

// ...
routing {
    openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml")
}

The plugin first looks for the specification in the application resources. If not found, it attempts to load it from the file system using java.io.File.

Generate runtime OpenAPI metadata

Instead of relying on a static file, you can generate the OpenAPI specification at runtime using metadata produced by the OpenAPI compiler plugin and route annotations.

In this mode, the OpenAPI plugin assembles the specification directly from the routing tree:

 openAPI(path = "openapi") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing {
        routingRoot.descendants()
    }
}

With this, you can access the generated OpenAPI documentation at the /openapi path, reflecting the current state of the application.

Configure OpenAPI

By default, documentation is rendered using StaticHtml2Codegen. You can customize the renderer inside the openAPI {} block:

    routing {
        openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml") {
            codegen = StaticHtmlCodegen()
        }
    }

23 January 2026