Multiple Api Specs

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 = "v1"
}) {
    //...
}

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" }
}

Configuring Routing for api-spec files and Swagger-UI

Routes for the spec-file and Swagger-UI have to be configured manually for each spec.

routing {

    // add routes for "v1"-spec and swagger-ui
    route("v1") {
    	route("api.json") {
            // api-spec containing all routes assigned to "v1"
            openApiSpec("version1")
        }
        route("swagger") {
            // swagger-ui using '/v1/api.json'
            swaggerUI("/v1/api.json")
        }
    }

    // add routes for "v2"-spec and swagger-ui
    route("v2") {
    	route("api.json") {
            // api-spec containing all routes assigned to "v2"
            openApiSpec("version2")
        }
        route("swagger") {
            // swagger-ui using '/v2/api.json'
            swaggerUI("/v2/api.json")
        }
    }

}

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) {

    // "global" configuration for all specs
    info {
        title = "Example API"
    }

    // configuration specific for spec "v1", overwrites global config
    spec("version1") {
        info {
            version = "1.0"
        }
    }

    // configuration specific for spec "v2", overwrites global config
    spec("version2") {
        info {
            version = "2.0"
        }
    }

}