Merge branch 'develop' into release

Author: SMILEY4

build.gradle.kts

@@ -1,5 +1,5 @@
 plugins {
-    kotlin("jvm") version "2.0.21"
+    kotlin("jvm") version "2.2.21"
     id("org.jetbrains.dokka") version "1.9.20" apply false
     id("org.owasp.dependencycheck") version "8.2.1" apply false
     id("io.gitlab.arturbosch.detekt") version "1.23.0" apply false

docs/assets/stylesheets/extra.css

@@ -16,4 +16,20 @@ details code {
         border-radius: .2rem !important;
         padding: 0 .3rem .3rem .3rem !important;
     }
+}
+
+.md-typeset h2 {
+    margin: 2.5em 0 .64em;
+}
+
+.md-typeset h2 {
+    margin: 2.6em 0 .64em;
+}
+
+.md-typeset h3 {
+    margin-top: 2.2em;
+}
+
+.md-content {
+    padding-bottom: 7em;
 }

docs/changelog.md

@@ -5,12 +5,20 @@ search:
 
 # Changelog
 
+## 5.4.0
+
+- support for ReDoc extensions `x-displayName` and `x-tagGroups` [#221](https://github.com/SMILEY4/ktor-openapi-tools/pull/221), [#219](https://github.com/SMILEY4/ktor-openapi-tools/pull/219)
+- complete overhaul of the documentation
+- upgrade schema-kenerator from 2.4.0 to [2.5.0](https://github.com/SMILEY4/schema-kenerator/releases/tag/2.5.0)
+- upgrade Ktor from 3.2.3 to 3.3.2
+- upgrade kotlin from 2.0.21 to 2.2.21
+
 ## 5.3.0
 
 - fix kotlinx-serialization example encoding [#212](https://github.com/SMILEY4/ktor-openapi-tools/issues/212)
 - fix missing response bodies from documented resources routes [#209](https://github.com/SMILEY4/ktor-openapi-tools/issues/209)
 - upgrade schema-kenerator from 2.3.0 to [2.4.0](https://github.com/SMILEY4/schema-kenerator/releases/tag/2.4.0)
-- upgrade ktor from 3.1.1 to ktor 3.3.0
+- upgrade ktor from 3.1.1 to ktor 3.2.3
 
 ## 5.2.0
 

docs/index.md

@@ -21,7 +21,7 @@ Designed to be non-invasive, they integrate seamlessly with applications without
 
     Add documentation to Ktor routes and automatically generate [OpenAPI](https://www.openapis.org/) specifications.
 
-    [:octicons-arrow-right-24: Get Started](openapi/index.md)
+    [:octicons-arrow-right-24: Read Documentation](./openapi/getting_started.md)
 
 
 -   :simple-swagger:{ .lg .middle } __Swagger UI__
@@ -32,7 +32,7 @@ Designed to be non-invasive, they integrate seamlessly with applications without
 
     Serve an interactive [Swagger UI](https://swagger.io/tools/swagger-ui/) for easy API exploration and testing
 
-    [:octicons-arrow-right-24: Get Started](swaggerui/index.md)
+    [:octicons-arrow-right-24: Read Documentation](swaggerui/index.md)
 
 
 -   :redoc:{ .lg .middle } __Redoc__
@@ -43,6 +43,6 @@ Designed to be non-invasive, they integrate seamlessly with applications without
 
     Serve an interactive [ReDoc](https://github.com/Redocly/redoc) page for easy API exploration and testing
 
-    [:octicons-arrow-right-24: Get Started](redoc/index.md)
+    [:octicons-arrow-right-24: Read Documentation](redoc/index.md)
 
 </div>

docs/openapi/advanced_topics/documenting_sse_routes.md

@@ -0,0 +1,36 @@
+# Documenting SSE Routes
+
+Server-Sent Events (SSE) routes can be documented for discoverability in the OpenAPI specification.
+While SSE functionality works normally in Ktor, documentation is achieved by wrapping SSE routes in a documented parent route.
+
+!!! warning "Limited OpenAPI Support"
+
+    OpenAPI has limited support for Server-Sent Events. The specification does not officially define SSE endpoints,
+    so not all documentation features work as expected or may not render correctly in documentation UIs.
+    
+    SSE documentation is primarily for discoverability and basic information. Advanced SSE features (event types, reconnection behavior,
+    stream format) are not well-represented in OpenAPI.
+
+
+## Describing SSE-Routes
+
+SSE routes are documented by wrapping them in a parent route with documentation:
+
+```kotlin
+import io.ktor.server.sse.sse
+
+route({
+    description = "Server-sent events stream for real-time updates"
+    tags = listOf("events", "sse")
+}) {
+    sse("/events") {
+        send(ServerSentEvent(data = "Hello"))
+    }
+}
+```
+
+??? info "More Information"
+
+    All standard route documentation options are available (in theory). For more information, see:
+
+    [:octicons-arrow-right-24: Basic Route Documentation](./../documenting_routes/basic_route_documentation.md)

docs/openapi/advanced_topics/documenting_webhooks.md

@@ -0,0 +1,41 @@
+# Documenting Webhooks
+
+Webhooks are HTTP callbacks that your API sends to external systems. While webhooks are not part of your server's request handling,
+they can be documented in the OpenAPI specification to help API consumers understand what data your API will send to their endpoints.
+
+!!! warning "Documentation Only"
+
+    Webhook documentation is purely informational. It does not create callable Ktor routes and has no impact on your application's routing or request handling.
+    
+    Webhooks appear only in the generated OpenAPI specification under the `webhooks` section. They document HTTP requests your API makes to external systems, not requests it receives.
+
+## Describing Webhooks
+
+Webhooks are documented using the webhook function:
+
+```kotlin
+routing {
+    route("webhooks") {
+        webhook(HttpMethod.Post, "concertAlert") {
+            description = "Notify the registered URL with details of an upcoming concert"
+            request {
+                body<String> {
+                    mediaTypes(ContentType.Text.Plain)
+                    required = true
+                }
+            }
+        }
+    }
+}
+```
+
+Parameters:
+
+- httpMethod: HTTP method for the webhook (typically HttpMethod.Post)
+- eventName: Unique identifier for the webhook event (e.g., "newOrder", "userCreated")
+
+??? info "More Information"
+
+    All standard route documentation options are available. For more information, see:
+
+    [:octicons-arrow-right-24: Basic Route Documentation](./../documenting_routes/basic_route_documentation.md)

docs/openapi/advanced_topics/multiple_openapi_specifications.md

@@ -0,0 +1,139 @@
+# Multiple API Specifications
+
+The OpenAPI plugin supports generating multiple independent specifications from a single application.
+This enables API versioning, separation of internal and external APIs, or organizing endpoints by product or team.
+
+Each specification has a unique identifier, its own configuration, and contains only the routes assigned to it.
+Specifications are generated and served independently.
+
+
+
+
+## Configuring Specifications
+
+Each specification can have its own configuration that extends or overrides the base plugin configuration.
+
+All configuration options available in the base plugin config are available for individual specifications:
+
+```kotlin
+install(OpenApi) {
+    info { // (1)!
+        title = "My API"
+    }
+    spec("v1") { // (2)!
+        info {
+            version = "1.0.0"
+        }
+    }
+    spec("v2") { // (3)!
+        info {
+            version = "2.0.0"
+        }
+    }
+}
+```
+
+1. Base configuration for all specifications
+2. Define and configure specification with identifier "v1"
+3. Define and configure specification with identifier "v2"
+
+Each specification is identified by a unique string (e.g., "v1", "v2", "internal").
+
+
+
+
+## Assigning Routes to Specifications
+
+Routes must be assigned to specifications to appear in them. Assignment can be done explicitly in route documentation or automatically via an assigner function.
+
+
+### Assignment at Route Documentation
+
+The `specName` property assigns a route to a specific specification:
+
+```kotlin
+get("users", {
+    specName = "v1"
+    description = "Get users (v1)"
+}) { }
+```
+
+Routes can be easily assigned in groups by adding the `specName` at a parent route:
+
+```kotlin
+route("v1", {
+    specName = "v1" // (1)!
+}) {
+    get("users") { }
+    get("products") { }
+    get("orders") { }
+}
+```
+
+1.  All child routes are assigned to "v1".
+
+All routes within this block are automatically assigned to the "v1" specification through inheritance.
+
+
+### Assignment via Assigner Function
+
+Routes can be automatically assigned based on their properties using an assigner function:
+
+```kotlin
+install(OpenApi) {
+    specAssigner = { url, tags ->
+        when (url.firstOrNull()) {
+            "v1" -> "v1"
+            "v2" -> "v2"
+            "internal" -> "internal"
+            else -> OpenApiPluginConfig.DEFAULT_SPEC_ID
+        }
+    }
+}
+```
+
+The function receives:
+
+- `url`: URL path as a list of segments (e.g., `["api", "v1", "users"]` for `/api/v1/users`)
+- `tags`: Tags assigned to the route
+
+The function returns the specification identifier to assign the route to.
+
+
+### Unassigned Routes
+
+Routes without an assignment are assigned to the default specification with the identifier `OpenApiPluginConfig.DEFAULT_SPEC_ID`.
+The default specification only exists if any routes are assigned to it.
+
+
+
+
+## Serving Multiple Specifications
+
+Each specification is served independently via HTTP routes.
+
+```kotlin
+routing {
+    route("v1/api.json") { // (1)!
+        openApi("v1")
+    }
+    route("v2/api.json") { // (2)!
+        openApi("v2")
+    }
+    route("internal/api.json") { // (3)!
+        openApi("internal")
+    }
+}
+```
+
+1. Expose v1 specification.
+2. Expose v2 specification.
+3. Expose internal specification.
+
+??? info "Multiple Specifications with Swagger UI and Redoc"
+
+    More information on how to handle multiple specifications with documentation UIs:
+
+    [:octicons-arrow-right-24: Swagger UI](./../../swaggerui/getting_started.md)
+
+    [:octicons-arrow-right-24: ReDoc](./../../redoc/getting_started.md)