Getting Started

Add Dependency

To generate OpenAPI specifications, you need to include the ktor-openapi artifact in the build script. All artifacts are published to Maven Central.

Gradle (Kotlin)GradleMaven

implementation("io.github.smiley4:ktor-openapi:$version")

implementation 'io.github.smiley4:ktor-openapi:$version'

<dependency>
    <groupId>io.github.smiley4</groupId>
    <artifactId>ktor-openapi</artifactId>
    <version>${version}</version>
</dependency>

Ktor Compatibility and Previous Versions

This project as been split into multiple projects starting with version 5.0.
Versions up to 5.0 are called ktor-swagger-ui instead of ktor-openapi.

Ktor	Plugin Version	Project Name
2.x	up to 3.x	ktor-swagger-ui
3.x	4.x	ktor-swagger-ui
3.x	5.x	ktor-openapi

Install OpenAPI

install(OpenApi) { //(1)!
    //...(2)
}

1. Install the "OpenAPI" plugin to the application.
2. Add additional plugin configuration here.

More Information

Plugin Configuration

API Reference

Exposing OpenAPI Specification

routing {
    route("api.json") { //(1)!
        openApi() //(2)!
    }
}

1. Create a new route to expose the OpenAPI specification file at api.json.
2. Expose the OpenAPI specification.

More Information

Multiple OpenAPI Specifications

API Reference

Documenting Routes

import io.github.smiley4.ktoropenapi.get //(1)!

get("hello", { //(2)!
    description = "A Hello-World route" //(3)!
    response {
        HttpStatusCode.OK to { //(4)!
            description = "A success response"
            body<String>() //(5)!
        }
    }
    //...
}) {
    call.respondText("Hello World!") //(6)!
}

1. Replace io.ktor.server.routing.get with io.github.smiley4.ktoropenapi.get. Same for other http methods.
2. Enrich /hello route with additional information.
3. Add a description to the route.
4. Document the different possible responses.
5. Specify the response body type. The schema for the type is generated automatically.
6. Handle requests as usual.

More Information

Documenting Routes

Documentation with Type-safe Routing

API Reference