OpenAPI
Ktor allows you to generate and serve OpenAPI documentation for your project based on the existing OpenAPI specification.
Add dependencies
Serving OpenAPI documentation requires adding the
ktor-server-openapi
artifact in the build script:implementation("io.ktor:ktor-server-openapi:$ktor_version")implementation "io.ktor:ktor-server-openapi:$ktor_version"<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-openapi-jvm</artifactId> <version>${ktor_version}</version> </dependency>Optionally, add the
swagger-codegen-generators
dependency if you want to customize a code generator:implementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")implementation "io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version"<dependency> <groupId>io.swagger.codegen.v3</groupId> <artifactId>swagger-codegen-generators</artifactId> <version>${swagger_codegen_version}</version> </dependency>You can replace
$swagger_codegen_version
with the required version of theswagger-codegen-generators
artifact, for example,1.0.36
.
Configure OpenAPI
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
:
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:
You can now run the application and open the /openapi
page to see the generated documentation.