Type-safe Routing

This project supports documenting Ktor routes defined using Type-safe Routing.

Documenting Routes

@Resource("{id}")
class Entity( //(1)!
    val id: String
)

1. Define resources classes as usual.

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

routing {
    get<Entity>({ //(2)!
        description = "Returns the entity with the requested id."
    }) {
        call.respond(HttpStatusCode.NotImplemented, Unit) //(3)!
    }
}

1. Replace io.ktor.server.resources.get with io.github.smiley4.ktoropenapi.resources.get. Same for other http methods.
2. Define the route using the resource class and add additional documentation.
3. Handle requests as usual.

More Information

See Documenting Routes for more general information.

Extracting Information from Resource Classes

When using type-safe routing, information about the routes can be extracted from the resources classes. This includes available query and path parameters with their names, types and whether they are optional. All other information still needs to be added manually and at the routes.

To enable automatic extraction, set the autoDocumentResourcesRoutes option in the plugin configuration.

install(OpenApi) {
    autoDocumentResourcesRoutes = true
}

Schema Generation

When using Type-safe routing and autoDocumentResourcesRoutes is enabled, schemas must be generated using kotlinx.serialization. See Schema Generation for more information on how to change the default generator.

install(OpenApi) {
    // enable automatically extracting documentation from resources-routes
    autoDocumentResourcesRoutes = true
    // schema-generator must use kotlinx-serialization to be compatible
    schemas {
        generator = SchemaGenerator.kotlinx()
    }
}