https://github.com/smiley4/ktor-openapi-tools
A collection of libraries to simplify API documentation and exploration for Ktor applications. Generates OpenAPI specifications and provides Swagger UI and ReDoc.
https://github.com/smiley4/ktor-openapi-tools
kotlin ktor ktor-plugin openapi redoc swagger swagger-ui
Last synced: 25 days ago
JSON representation
A collection of libraries to simplify API documentation and exploration for Ktor applications. Generates OpenAPI specifications and provides Swagger UI and ReDoc.
- Host: GitHub
- URL: https://github.com/smiley4/ktor-openapi-tools
- Owner: SMILEY4
- License: apache-2.0
- Created: 2022-08-20T11:29:42.000Z (almost 3 years ago)
- Default Branch: develop
- Last Pushed: 2025-03-31T16:35:06.000Z (2 months ago)
- Last Synced: 2025-04-03T22:08:27.282Z (2 months ago)
- Topics: kotlin, ktor, ktor-plugin, openapi, redoc, swagger, swagger-ui
- Language: Kotlin
- Homepage: https://smiley4.github.io/ktor-openapi-tools/
- Size: 3.85 MB
- Stars: 213
- Watchers: 4
- Forks: 36
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ktor OpenAPI Tools
[](https://search.maven.org/search?q=g:io.github.smiley4%20a:ktor-openapi)
[](https://github.com/SMILEY4/ktor-openapi-tools/actions/workflows/checks.yml)
[](https://github.com/SMILEY4/ktor-openapi-tools/blob/develop/LICENSE)
A collection of libraries to simplify API documentation and exploration for [Ktor](https://ktor.io/) applications. Designed to be non-invasive, they integrate seamlessly with applications without requiring immediate change to existing code while being highly customizable to fit every use case.
**Documentation** can be found [here](https://smiley4.github.io/ktor-openapi-tools/latest/) and in the [wiki](https://github.com/SMILEY4/ktor-openapi-tools/wiki) for older versions.
## OpenAPI
Ktor plugin to automatically generate [OpenAPI](https://www.openapis.org/) specifications from routes. Additional information can be gradually added to existing routes without requiring major changes to existing code.
- Extends existing Ktor DSL
- No immediate change to code required
- Support for [Type-safe routing](https://ktor.io/docs/server-resources.html) / Resources plugin
- Document webhooks and (limited) options for server-sent events
- Covers (almost) complete [OpenAPI 3.1.0 Specification](https://swagger.io/specification/)
- Automatically generates json schemas from kotlin types
- Out-of-the-box support for type parameters, inheritance, collections, etc
- Usable with reflection or [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization)
- Supports [Jackson](https://github.com/FasterXML/jackson), [Swagger](https://github.com/swagger-api/swagger-core), [Javax](https://mvnrepository.com/artifact/javax.validation/validation-api)
and [Jakarta](https://github.com/jakartaee/validation/tree/main) annotations
- Highly configurable and customizable
```kotlin
// Install and configure the OpenAPI plugin.
install(OpenApi)
routing {
route("api.json") {
// Create a route to expose the OpenAPI specification file at `/api.json`.
openApi()
}
get("example", {
// Add (optional) information to the route, e.g. a description and responses and response bodies.
description = "An example route"
response {
HttpStatusCode.OK to {
description = "A success response"
body()
}
}
}) {
// Handle requests as usual.
call.respondText("Hello World!")
}
}
```
## Swagger UI
Library for Ktor applications to serve [Swagger UI](https://swagger.io/tools/swagger-ui/) - visualize and interact with generated OpenAPI specifications.
- Explore and interact with OpenAPI specifications generated by [`ktor-openapi`](../openapi/index.md) or external specifications
- Serve bundled Swagger UI
- Expose multiple "instances" of Swagger UI (e.g. for different OpenAPI specifications)
- All Swagger UI configuration options available
```kotlin
routing {
route("swagger") {
// Expose Swagger UI using OpenAPI specification at `/api.json`.
// Path can be relative pointing to specification provided by this application or absolute pointing to an external resource.
swaggerUI("/api.json") {
// Add configuration for this Swagger UI "instance" here.
}
}
}
```
## ReDoc
Library for Ktor applications to serve [ReDoc](https://github.com/Redocly/redoc) - visualize and interact with generated OpenAPI specifications.
- Explore and interact with OpenAPI specifications generated by [`ktor-openapi`](../openapi/index.md) or external specifications
- Serve bundled ReDoc page
- Expose multiple "instances" of ReDoc (e.g. for different OpenAPI specifications)
- All ReDoc configuration options available
```kotlin
routing {
route("redoc") {
// Expose ReDoc showing OpenAPI specification at `/api.json`.
// Path can be relative pointing to specification provided by this application or absolute pointing to an external resource.
redoc("/api.json") {
// Add configuration for this ReDoc "instance" here.
}
}
}
```