|
1 | | -# Ktor Swagger-UI |
| 1 | +# Ktor OpenAPI Tools |
2 | 2 |
|
3 | | -[](https://search.maven.org/artifact/io.github.smiley4/ktor-swagger-ui) |
4 | | -[](https://github.com/SMILEY4/ktor-swagger-ui/actions/workflows/checks.yml) |
| 3 | +[](https://search.maven.org/search?q=g:io.github.smiley4%20a:ktor-openapi) |
| 4 | +[](https://github.com/SMILEY4/ktor-openapi-tools/actions/workflows/checks.yml) |
| 5 | +[](https://github.com/SMILEY4/ktor-openapi-tools/blob/develop/LICENSE) |
5 | 6 |
|
6 | | -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. |
| 7 | +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. |
7 | 8 |
|
| 9 | +**Documentation** can be found [here](https://smiley4.github.io/ktor-openapi-tools/latest/). |
8 | 10 |
|
9 | | -## Features |
10 | 11 |
|
11 | | -- minimally invasive (no immediate change to existing code required) |
12 | | -- provides swagger-ui and openapi-spec with minimal configuration |
13 | | -- supports most of the [OpenAPI 3.1.0 Specification](https://swagger.io/specification/) |
14 | | -- automatic [json-schema generation](https://github.com/SMILEY4/schema-kenerator) from arbitrary types/classes for bodies and parameters |
15 | | - - supports generics, inheritance, collections, ... |
16 | | - - support for Jackson-annotations and swagger Schema-annotations (optional) |
17 | | - - use with reflection or kotlinx-serialization |
18 | | - - customizable schema-generation |
| 12 | +## OpenAPI |
19 | 13 |
|
| 14 | +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. |
20 | 15 |
|
21 | | -## Documentation |
22 | | - |
23 | | -A wiki with a short documentation is available [here](https://github.com/SMILEY4/ktor-swagger-ui/wiki). |
24 | | - |
25 | | - |
26 | | -## Installation |
| 16 | +- Extends existing Ktor DSL |
| 17 | +- No immediate change to code required |
| 18 | +- Support for [Type-safe routing](https://ktor.io/docs/server-resources.html) / Resources plugin |
| 19 | +- Document webhooks and (limited) options for server-sent events |
| 20 | +- Covers (almost) complete [OpenAPI 3.1.0 Specification](https://swagger.io/specification/) |
| 21 | +- Automatically generates json schemas from kotlin types |
| 22 | + - Out-of-the-box support for type parameters, inheritance, collections, etc |
| 23 | + - Usable with reflection or [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) |
| 24 | + - Supports [Jackson](https://github.com/FasterXML/jackson), [Swagger](https://github.com/swagger-api/swagger-core), [Javax](https://mvnrepository.com/artifact/javax.validation/validation-api) |
| 25 | + and [Jakarta](https://github.com/jakartaee/validation/tree/main) annotations |
| 26 | + - Highly configurable and customizable |
27 | 27 |
|
28 | 28 | ```kotlin |
29 | | -dependencies { |
30 | | - implementation "io.github.smiley4:ktor-swagger-ui:<VERSION>" |
| 29 | +// Install and configure the OpenAPI plugin. |
| 30 | +install(OpenApi) |
| 31 | + |
| 32 | +routing { |
| 33 | + |
| 34 | + route("api.json") { |
| 35 | + // Create a route to expose the OpenAPI specification file at `/api.json`. |
| 36 | + openApi() |
| 37 | + } |
| 38 | + |
| 39 | + get("example", { |
| 40 | + // Add (optional) information to the route, e.g. a description and responses and response bodies. |
| 41 | + description = "An example route" |
| 42 | + response { |
| 43 | + HttpStatusCode.OK to { |
| 44 | + description = "A success response" |
| 45 | + body<String>() |
| 46 | + } |
| 47 | + } |
| 48 | + }) { |
| 49 | + // Handle requests as usual. |
| 50 | + call.respondText("Hello World!") |
| 51 | + } |
31 | 52 | } |
32 | 53 | ``` |
33 | 54 |
|
34 | 55 |
|
35 | | -## Ktor compatibility |
36 | | - |
37 | | -- Ktor 2.x: ktor-swagger-ui up to 3.x |
38 | | -- Ktor 3.x: ktor-swagger-ui starting with 4.0 |
| 56 | +## Swagger UI |
39 | 57 |
|
| 58 | +Library for Ktor applications to serve [Swagger UI](https://swagger.io/tools/swagger-ui/) - visualize and interact with generated OpenAPI specifications. |
40 | 59 |
|
41 | | -## Examples |
| 60 | +- Explore and interact with OpenAPI specifications generated by [`ktor-openapi`](../openapi/index.md) or external specifications |
| 61 | +- Serve bundled Swagger UI |
| 62 | +- Expose multiple "instances" of Swagger UI (e.g. for different OpenAPI specifications) |
| 63 | +- All Swagger UI configuration options available |
42 | 64 |
|
43 | | -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). |
44 | | - |
45 | | - |
46 | | -### Configuration |
47 | | - |
48 | | -```kotlin |
49 | | -install(SwaggerUI) { |
50 | | - swagger { |
51 | | - swaggerUrl = "swagger-ui" |
52 | | - forwardRoot = true |
53 | | - } |
54 | | - info { |
55 | | - title = "Example API" |
56 | | - version = "latest" |
57 | | - description = "Example API for testing and demonstration purposes." |
58 | | - } |
59 | | - server { |
60 | | - url = "http://localhost:8080" |
61 | | - description = "Development Server" |
62 | | - } |
63 | | -} |
64 | | -``` |
65 | 65 | ```kotlin |
66 | 66 | routing { |
67 | | - // Create a route for the openapi-spec file. |
68 | | - route("api.json") { |
69 | | - openApiSpec() |
70 | | - } |
71 | | - // Create a route for the swagger-ui using the openapi-spec at "/api.json". |
| 67 | + |
72 | 68 | route("swagger") { |
73 | | - swaggerUI("/api.json") |
| 69 | + // Expose Swagger UI using OpenAPI specification at `/api.json`. |
| 70 | + // Path can be relative pointing to specification provided by this application or absolute pointing to an external resource. |
| 71 | + swaggerUI("/api.json") { |
| 72 | + // Add configuration for this Swagger UI "instance" here. |
| 73 | + } |
74 | 74 | } |
| 75 | + |
75 | 76 | } |
76 | 77 | ``` |
77 | 78 |
|
78 | | -### Routes |
79 | 79 |
|
80 | | -```kotlin |
81 | | -get("hello", { |
82 | | - description = "Hello World Endpoint." |
83 | | - response { |
84 | | - HttpStatusCode.OK to { |
85 | | - description = "Successful Request" |
86 | | - body<String> { description = "the response" } |
87 | | - } |
88 | | - HttpStatusCode.InternalServerError to { |
89 | | - description = "Something unexpected happened" |
90 | | - } |
91 | | - } |
92 | | -}) { |
93 | | - call.respondText("Hello World!") |
94 | | -} |
95 | | -``` |
| 80 | +## ReDoc |
| 81 | + |
| 82 | +Library for Ktor applications to serve [ReDoc](https://github.com/Redocly/redoc) - visualize and interact with generated OpenAPI specifications. |
| 83 | + |
| 84 | +- Explore and interact with OpenAPI specifications generated by [`ktor-openapi`](../openapi/index.md) or external specifications |
| 85 | +- Serve bundled ReDoc page |
| 86 | +- Expose multiple "instances" of ReDoc (e.g. for different OpenAPI specifications) |
| 87 | +- All ReDoc configuration options available |
96 | 88 |
|
97 | 89 | ```kotlin |
98 | | -post("math/{operation}", { |
99 | | - tags = listOf("test") |
100 | | - description = "Performs the given operation on the given values and returns the result" |
101 | | - request { |
102 | | - pathParameter<String>("operation") { |
103 | | - description = "the math operation to perform. Either 'add' or 'sub'" |
104 | | - } |
105 | | - body<MathRequest>() |
106 | | - } |
107 | | - response { |
108 | | - HttpStatusCode.OK to { |
109 | | - description = "The operation was successful" |
110 | | - body<MathResult> { |
111 | | - description = "The result of the operation" |
112 | | - } |
113 | | - } |
114 | | - HttpStatusCode.BadRequest to { |
115 | | - description = "An invalid operation was provided" |
116 | | - } |
117 | | - } |
118 | | -}) { |
119 | | - val operation = call.parameters["operation"]!! |
120 | | - call.receive<MathRequest>().let { request -> |
121 | | - when (operation) { |
122 | | - "add" -> call.respond(HttpStatusCode.OK, MathResult(request.a + request.b)) |
123 | | - "sub" -> call.respond(HttpStatusCode.OK, MathResult(request.a - request.b)) |
124 | | - else -> call.respond(HttpStatusCode.BadRequest, Unit) |
| 90 | +routing { |
| 91 | + |
| 92 | + route("redoc") { |
| 93 | + // Expose ReDoc showing OpenAPI specification at `/api.json`. |
| 94 | + // Path can be relative pointing to specification provided by this application or absolute pointing to an external resource. |
| 95 | + redoc("/api.json") { |
| 96 | + // Add configuration for this ReDoc "instance" here. |
125 | 97 | } |
126 | 98 | } |
| 99 | + |
127 | 100 | } |
128 | | - |
129 | | -data class MathRequest( |
130 | | - val a: Int, |
131 | | - val b: Int |
132 | | -) |
133 | | - |
134 | | -data class MathResult( |
135 | | - val value: Int |
136 | | -) |
137 | | -``` |
138 | | - |
| 101 | +``` |
0 commit comments