Skip to content

SMILEY4/ktor-swagger-ui

Folders and files

NameName
Last commit message
Last commit date
Jun 22, 2024
Jun 13, 2024
Oct 14, 2024
Jan 15, 2025
Jan 29, 2025
Aug 19, 2022
Aug 31, 2022
Oct 24, 2024
Oct 16, 2024
Jan 11, 2025
May 16, 2024
Aug 19, 2022
Oct 14, 2024

Repository files navigation

Ktor Swagger-UI

Maven Central Checks Passing

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
  • automatic json-schema generation 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.

Installation

dependencies {
    implementation "io.github.smiley4:ktor-swagger-ui:<VERSION>"
}

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.

Configuration

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"
    }
}
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

get("hello", {
    description = "Hello World Endpoint."
    response {
        HttpStatusCode.OK to {
            description = "Successful Request"
            body<String> { description = "the response" }
        }
        HttpStatusCode.InternalServerError to {
            description = "Something unexpected happened"
        }
    }
}) {
    call.respondText("Hello World!")
}
post("math/{operation}", {
    tags = listOf("test")
    description = "Performs the given operation on the given values and returns the result"
    request {
        pathParameter<String>("operation") {
            description = "the math operation to perform. Either 'add' or 'sub'"
        }
        body<MathRequest>()
    }
    response {
        HttpStatusCode.OK to {
            description = "The operation was successful"
            body<MathResult> {
                description = "The result of the operation"
            }
        }
        HttpStatusCode.BadRequest to {
            description = "An invalid operation was provided"
        }
    }
}) {
    val operation = call.parameters["operation"]!!
    call.receive<MathRequest>().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
)