V2 Multiple Swagger UIs - SMILEY4/ktor-openapi-tools GitHub Wiki

A working example can be found here.

Assigning Routes to a specific OpenApi-Spec

Routes can be assigned in two ways

Assign routes with flags

A single route can be assigned to a specific openapi-spec by setting the flag to the name/id of the spec.

get("example", {
    specId = "mySpecId"
}) {
    //...
}

This can also be done for a whole group of routes by adding it to a higher up "route".

route("v1", {
	specId = "v1" // assigns all child routes to the spec "v1"
})  {
    
    get("example", {}) { /*...*/ }
    post("example", {}) { /*...*/ }
    delete("example", {}) { /*...*/ }
    
}

Assign routes with spec-assigner

The spec-assigner in the plugin config is given the url (as a list of parts) and the tags of all routes and provides the name/id of an openapi-spec to assign the route to. This will only be done for routes that don't have a spec assigned already via a flag.

install(SwaggerUI) {
    //...
    specAssigner = { url, tags -> url.firstOrNull() ?: "default" }
}

Accessing Swagger-UI

Each openapi-spec and swagger-ui a route has been assigned to is available at /{rootHostPath}/{swaggerUrl}/{specName}.

For example (assuming default configuration) two spec with the names/ids "v1" and "v2" will be available at

• http://localhost:8080/swagger-ui/v1/index.html
• http://localhost:8080/swagger-ui/v1/v1.json
• http://localhost:8080/swagger-ui/v2/index.html
• http://localhost:8080/swagger-ui/v2/v2.json

If only a single spec is present, the default path /{rootHostPath}/{swaggerUrl} (without the spec-name) is used.

Configuring individual OpenApi-Specs

Every individual openApi-spec and Swagger-UI can be fully customized. The normal plugin-config serves as a base for all specs, which can then be overwritten.

install(SwaggerUI) {
    
    // general configuration
    info {
        title = "Example API"
    }
    
    // configuration specific for spec "v1"
    spec("v1") {
        info {
            version = "1.0"
        }
    }
    
    // configuration specific for spec "v2"
    spec("v2") {
        info {
            version = "2.0"
        }
        swagger {
            authentication = "auth-swagger"
        }
    }
}