Swagger UI

Ktor allows you to generate and serve Swagger UI for your project based on an OpenAPI specification. With Swagger UI, you can visualize and interact with your API endpoints directly from the browser.

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.

Add dependencies

Serving Swagger UI requires adding the ktor-server-swagger artifact in the build script:

implementation("io.ktor:ktor-server-swagger:$ktor_version")

implementation "io.ktor:ktor-server-swagger:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-server-swagger-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Use a static OpenAPI file

To serve Swagger UI from an existing OpenAPI specification file, use the swaggerUI() function and specify the file location.

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

import io.ktor.server.plugins.swagger.*

// ...
routing {
    swaggerUI(path = "swagger", 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:

swaggerUI("/swaggerUI") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing(ContentType.Application.Json) {
        routingRoot.descendants()
    }
}

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

Configure Swagger UI

The swaggerUI {} configuration block lets you configure the OpenAPI document and customize Swagger UI.

Configure document metadata

You can define top-level OpenAPI metadata directly in the configuration block.

For example, use info to specify general API information and tag() to define tags and their descriptions:

swaggerUI("/swagger") {
    info = OpenApiInfo("Books API from routes", "1.0.0")
    tag(
        name = "Books",
        description = "Operations on books"
    )
}

You can also configure other top-level OpenAPI properties, such as servers, security requirements, reusable components, external documentation, and specification extensions.

Configure the Swagger UI version

By default, Ktor uses a predefined Swagger UI version. To use a different version, set the version property:

    routing {
        swaggerUI(path = "swagger", swaggerFile = "openapi/documentation.yaml") {
            version = "5.31.0"
        }
    }

Configure CORS

To ensure Swagger UI can access your API endpoints correctly, you need to first configure Cross-Origin Resource Sharing (CORS).

The example below applies the following CORS configuration:

anyHost enables cross-origin requests from any host.
allowHeader allows the Content-Type client header used for content negotiation.

    install(CORS) {
        anyHost()
        allowHeader(HttpHeaders.ContentType)
    }

19 August 2026