Required dependencies: io.ktor:%artifact_name%
Ktor allows you to generate and serve OpenAPI documentation for your project based on the existing OpenAPI specification.
-
Serving OpenAPI documentation requires adding the
%artifact_name%
artifact in the build script: -
Optionally, add the
swagger-codegen-generators
dependency if you want to customize a code generator:You can replace
$swagger_codegen_version
with the required version of theswagger-codegen-generators
artifact, for example,%swagger_codegen_version%
.
To serve OpenAPI documentation, you need to call the openAPI method that creates a GET
endpoint with documentation
at the path
rendered from the OpenAPI specification placed at swaggerFile
:
import io.ktor.server.plugins.openapi.*
// ...
routing {
openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml")
}
This method tries to look up the OpenAPI specification in the application resources.
Otherwise, it tries to read the OpenAPI specification from the file system using java.io.File
.
By default, the documentation is generated using StaticHtml2Codegen
.
You can customize generation settings inside the openAPI
block:
{src="snippets/json-kotlinx-openapi/src/main/kotlin/com/example/Application.kt" include-lines="39,55-58"}
You can now run the application and open the /openapi
page to see the generated documentation.