OpenAPI
Ktor allows you to generate and serve OpenAPI documentation for your project based on an existing OpenAPI specification. You can serve an existing YAML or JSON specification, or generate one using the OpenAPI extension of the Ktor Gradle plugin.
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.