Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smiley4/ktor-swagger-ui
Kotlin Ktor plugin to generate OpenAPI and provide Swagger UI
https://github.com/smiley4/ktor-swagger-ui
kotlin ktor ktor-plugin openapi swagger swagger-ui
Last synced: 1 day ago
JSON representation
Kotlin Ktor plugin to generate OpenAPI and provide Swagger UI
- Host: GitHub
- URL: https://github.com/smiley4/ktor-swagger-ui
- Owner: SMILEY4
- License: apache-2.0
- Created: 2022-08-20T11:29:42.000Z (about 2 years ago)
- Default Branch: develop
- Last Pushed: 2024-11-04T20:36:42.000Z (3 days ago)
- Last Synced: 2024-11-04T21:28:50.878Z (3 days ago)
- Topics: kotlin, ktor, ktor-plugin, openapi, swagger, swagger-ui
- Language: Kotlin
- Homepage:
- Size: 846 KB
- Stars: 178
- Watchers: 5
- Forks: 33
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ktor Swagger-UI
[](https://search.maven.org/artifact/io.github.smiley4/ktor-swagger-ui)
[](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml)
This library provides a Ktor plugin to document routes, generate an OpenApi Specification and serve a Swagger UI. It is meant to be minimally invasive, meaning it can be plugged into existing application without requiring immediate changes to the code. Routes can then be gradually enhanced with documentation.
## Features
- minimally invasive (no immediate change to existing code required)
- provides swagger-ui and openapi-spec with minimal configuration
- supports most of the [OpenAPI 3.1.0 Specification](https://swagger.io/specification/)
- automatic [json-schema generation](https://github.com/SMILEY4/schema-kenerator) from arbitrary types/classes for bodies and parameters
- supports generics, inheritance, collections, ...
- support for Jackson-annotations and swagger Schema-annotations (optional)
- use with reflection or kotlinx-serialization
- customizable schema-generation
## Documentation
A wiki with a short documentation is available [here](https://github.com/SMILEY4/ktor-swagger-ui/wiki).
## Installation
```kotlin
dependencies {
implementation "io.github.smiley4:ktor-swagger-ui:"
}
```
## Ktor compatibility
- Ktor 2.x: ktor-swagger-ui up to 3.x
- Ktor 3.x: ktor-swagger-ui starting with 4.0
## Examples
Runnable examples can be found in [ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples](https://github.com/SMILEY4/ktor-swagger-ui/tree/release/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples).
### Configuration
```kotlin
install(SwaggerUI) {
swagger {
swaggerUrl = "swagger-ui"
forwardRoot = true
}
info {
title = "Example API"
version = "latest"
description = "Example API for testing and demonstration purposes."
}
server {
url = "http://localhost:8080"
description = "Development Server"
}
}
```
```kotlin
routing {
// Create a route for the openapi-spec file.
route("api.json") {
openApiSpec()
}
// Create a route for the swagger-ui using the openapi-spec at "/api.json".
route("swagger") {
swaggerUI("/api.json")
}
}
```
### Routes
```kotlin
get("hello", {
description = "Hello World Endpoint."
response {
HttpStatusCode.OK to {
description = "Successful Request"
body { description = "the response" }
}
HttpStatusCode.InternalServerError to {
description = "Something unexpected happened"
}
}
}) {
call.respondText("Hello World!")
}
```
```kotlin
post("math/{operation}", {
tags = listOf("test")
description = "Performs the given operation on the given values and returns the result"
request {
pathParameter("operation") {
description = "the math operation to perform. Either 'add' or 'sub'"
}
body()
}
response {
HttpStatusCode.OK to {
description = "The operation was successful"
body {
description = "The result of the operation"
}
}
HttpStatusCode.BadRequest to {
description = "An invalid operation was provided"
}
}
}) {
val operation = call.parameters["operation"]!!
call.receive().let { request ->
when (operation) {
"add" -> call.respond(HttpStatusCode.OK, MathResult(request.a + request.b))
"sub" -> call.respond(HttpStatusCode.OK, MathResult(request.a - request.b))
else -> call.respond(HttpStatusCode.BadRequest, Unit)
}
}
}
data class MathRequest(
val a: Int,
val b: Int
)
data class MathResult(
val value: Int
)
```