Ktor OpenAPI Tools

A collection of libraries to simplify API documentation and exploration for Ktor 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 and in the wiki for older versions.

OpenAPI

Ktor plugin to automatically generate OpenAPI 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 / Resources plugin
• Document webhooks and (limited) options for server-sent events
• Covers (almost) complete OpenAPI 3.1.0 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
  • Supports Jackson, Swagger, Javax and Jakarta annotations
  • Highly configurable and customizable

// 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<String>()
            }
        }
    }) {
        // Handle requests as usual.
        call.respondText("Hello World!")
    }
}

Swagger UI

Library for Ktor applications to serve Swagger UI - visualize and interact with generated OpenAPI specifications.

• Explore and interact with OpenAPI specifications generated by ktor-openapi 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

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 - visualize and interact with generated OpenAPI specifications.

• Explore and interact with OpenAPI specifications generated by ktor-openapi or external specifications
• Serve bundled ReDoc page
• Expose multiple "instances" of ReDoc (e.g. for different OpenAPI specifications)
• All ReDoc configuration options available

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