The Ktor OpenAPI Generator is a library to automatically generate the descriptor as you route your ktor application.
dependencies {
implementation("no.nav:ktor-openapi-generator:1.0.46")
}
See MinimalExample.kt for minimal example app and then MinimalExampleTest.kt that it actually works.
/**
* Minimal example of OpenAPI plugin for Ktor.
*/
fun Application.minimalExample() {
// install OpenAPI plugin
install(OpenAPIGen) {
// this servers OpenAPI definition on /openapi.json
serveOpenApiJson = true
// this servers Swagger UI on /swagger-ui/index.html
serveSwaggerUi = true
info {
title = "Minimal Example API"
}
}
// install JSON support
install(ContentNegotiation) {
jackson()
}
// and now example routing
apiRouting {
route("/example/{name}") {
// SomeParams are parameters (query or path), SomeResponse is what the backend returns and SomeRequest
// is what was passed in the body of the request
post<SomeParams, SomeResponse, SomeRequest> { params, someRequest ->
respond(SomeResponse(bar = "Hello ${params.name}! From body: ${someRequest.foo}."))
}
}
}
}
data class SomeParams(@PathParam("who to say hello") val name: String)
data class SomeRequest(val foo: String)
data class SomeResponse(val bar: String)
To serve the Swagger UI, put this in version.properties
(in resources
):
swagger-ui.version=5.17.14
Ktor OpenAPI Generator is:
- Modular
- Strongly typed
- Explicit
Currently Supported:
- Authentication interoperability with strongly typed Principal (OAuth only, see TestServer in tests)
- Content Negotiation interoperability (see TestServer in tests)
- Custom response codes (as parameter in
@Response
) - Automatic and custom content Type routing and parsing (see
com.papsign.ktor.openapigen.content.type
, Binary Parser and default JSON parser (that uses the ktor implicit parsing/serializing)) - Exception handling (use
.throws(ex) {}
in the routes with an APIException object) with Status pages interop (with .withAPI in the StatusPages configuration) - tags (
.tag(tag) {}
in route with a tag object, currently must be an enum, but may be subject to change) - Spec compliant Parameter Parsing (see basic example)
- Legacy Polymorphism with use of
@DiscriminatorAnnotation()
attribute and sealed classes
Extra Features:
- Includes Swagger-UI (enabled by default, can be managed in the
install(OpenAPIGen) { ... }
section)
Take a look at a few examples