Getting Started

Add Dependency

dependencies {
    implementation "io.github.smiley4:ktor-swagger-ui:<VERSION>"
}

Versions < 2.2.0 are hosted on Jitpack and the repository has to be added:

repositories {
    maven { url = uri("https://jitpack.io") }
}

Install Plugin

Install the Swagger-UI ktor-plugin. Plugin configuration is "optional" and default values are used.

install(SwaggerUI) {
    //...
}

For more information about plugin configuration see:

• Plugin and Swagger-UI
• OpenApi-Specification
• Multiple Api-Specs

Routing for Swagger-UI and OpenApi-Spec

Routes for Swagger-UI and the api-spec file must be configured manually.

routing {
    route("myApi.json") {
        openApiSpec() // api-spec json is served at '/myApi.json'
    }
    route("mySwagger") {
        swaggerUI("/myApi.json") // swagger-ui is available at '/mySwagger' or '/mySwagger/index.html'
    }
}

• openApiSpec() adds the route for the api-spec json-file
• swaggerUi(apiSpecUrl) adds the routes for the swagger-ui and all required static resources. The url of the api-spec json-file to use must be provided.

For more information about routing with multiple independent api-specs, see:

• Multiple Api-Specs

Documenting Routes

The Swagger-UI plugin provides functions to create documented get, post, put, delete, patch, options, head, route and method routes. These work exactly the same as their respective base Ktor-functions, but allow OpenAPI documentation to be added. Functions to create routes provided by the plugin and those from Ktor can be mixed and allow for a gradual enhancement of the api with documentation.

Documentation can be added at any level and documentation of parent and child routes are merged together, with priority given to the deepest route. (Example: the "route" and a nested "get" have a "description" set. When the two documentations are merged, the description of the "get" takes priority).

routing {
    
    route("api", {
        // possible to add api-documentation here...
    }) {
        
        // a documented route
        get("hello", {
            
            // description of the route
            description = "A Hello-World route"
            
            // information about the request
            request {
                // information about the query-parameter "name" of type "string"
                queryParameter<String>("name") {
                    description = "the name to greet"
                }
            }
            
            // information about possible responses
            response {
                
                // information about a "200 OK" response
                HttpStatusCode.OK to {
                
                    // a description of the response
                    description = "successful request - always returns 'Hello World!'"
                    
                    // information about the response bofy of type "string"
                    body<String>() {
                        description = "successful response body"
                    }
                }
            }
        }) {
            // handle the request ...
            call.respondText("Hello ${call.request.queryParameters["name"]}")
        }
        
    }
    
}

For more information about documenting routes, see:

• Basic Information
• Types and Schemas
• Customizing Schemas
• Example Configuration and Shared Examples

Examples

Runnable examples can be found here:

• ktor-swagger-ui-examples