Add OpenAPI Extensions support for Route documentation

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/openapi/OperationBuilder.kt

@@ -42,6 +42,8 @@ internal class OperationBuilder(
             if (route.documentation.servers.isNotEmpty()) {
                 it.servers = route.documentation.servers.map { server -> serverBuilder.build(server) }
             }
+            if (route.documentation.extensions.isNotEmpty()) {
+                it.extensions = route.documentation.extensions
+            }
         }
-
 }

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/route/RouteDocumentationMerger.kt

@@ -38,7 +38,9 @@ internal class RouteDocumentationMerger {
                     a.getResponses().getResponses().forEach { this[it.statusCode] = it }
                 }.values.forEach { addResponse(it) }
             }
+            extensions = a.extensions.toMutableMap().also { merged ->
+                b.extensions.forEach { merged[it.key] = it.value }
+            }
         }
     }
-
 }

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/config/RouteConfig.kt

@@ -146,6 +146,24 @@ class RouteConfig internal constructor() {
 
     private val servers = mutableListOf<ServerConfig>()
 
+    /**
+     * A list of extensions to the OpenAPI Schema.
+     * The field name MUST begin with x-, for example, x-internal-id.
+     * Field names beginning x-oai- and x-oas- are reserved for uses defined by the OpenAPI Initiative.
+     * The value can be null, a primitive, an array or an object.
+     */
+    var extensions: Map<String, Any?> = emptyMap()
+
+    /**
+     * Sets extensions to the OpenAPI Schema.
+     * The field name MUST begin with x-, for example, x-internal-id.
+     * Field names beginning x-oai- and x-oas- are reserved for uses defined by the OpenAPI Initiative.
+     * The value can be null, a primitive, an array or an object.
+     */
+    fun extensions(extensions: Map<String, Any?>) {
+        this.extensions = extensions
+    }
+
     /**
      * Build the data object for this config.
      */
@@ -162,7 +180,8 @@ class RouteConfig internal constructor() {
         request = request.build(),
         responses = responses.getResponses().map { it.build() },
         externalDocs = externalDocs?.build(ExternalDocsData.DEFAULT),
-        servers = servers.map { it.build(ServerData.DEFAULT) }
+        servers = servers.map { it.build(ServerData.DEFAULT) },
+        extensions = extensions,
     )
 
 }

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/data/RouteData.kt

@@ -17,4 +17,5 @@ internal data class RouteData(
     val responses: List<ResponseData>,
     val externalDocs: ExternalDocsData?,
     val servers: List<ServerData>,
+    val extensions: Map<String, Any?>
 )

ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OperationBuilderTest.kt

@@ -1010,6 +1010,53 @@ class OperationBuilderTest : StringSpec({
         }
     }
 
+    "route with extensions" {
+        val route = RouteMeta(
+            path = "/test",
+            method = HttpMethod.Get,
+            documentation = RouteConfig().also { route ->
+                route.summary = "test route with extensions"
+                route.description = "route for testing extensions"
+                route.extensions = mapOf(
+                    "x-custom-extension" to "custom-value",
+                    "x-another-extension" to mapOf(
+                        "nested" to "value",
+                        "number" to 42
+                    ),
+                    "x-simple-flag" to true
+                )
+            }.build(),
+            protected = false,
+            isWebhook = false,
+        )
+        val schemaContext = schemaContext(listOf(route))
+        val exampleContext = exampleContext(listOf(route))
+        buildOperationObject(route, schemaContext, exampleContext).also { operation ->
+            operation.tags.shouldBeEmpty()
+            operation.summary shouldBe "test route with extensions"
+            operation.description shouldBe "route for testing extensions"
+            operation.externalDocs shouldBe null
+            operation.operationId shouldBe null
+            operation.parameters.shouldBeEmpty()
+            operation.requestBody shouldBe null
+            operation.responses.shouldBeEmpty()
+            operation.deprecated shouldBe false
+            operation.security shouldBe null
+            operation.servers shouldBe null
+            operation.extensions
+                .also { it.shouldNotBeNull() }
+                ?.also { extensions ->
+                    extensions shouldHaveSize 3
+                    extensions["x-custom-extension"] shouldBe "custom-value"
+                    extensions["x-another-extension"] shouldBe mapOf(
+                        "nested" to "value",
+                        "number" to 42
+                    )
+                    extensions["x-simple-flag"] shouldBe true
+                }
+        }
+    }
+
 }) {
 
     companion object {

ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/misc/RouteDocumentationMergerTest.kt

@@ -6,6 +6,7 @@ import io.github.smiley4.ktoropenapi.config.RouteConfig
 import io.kotest.core.spec.style.StringSpec
 import io.kotest.matchers.collections.shouldBeEmpty
 import io.kotest.matchers.collections.shouldContainExactlyInAnyOrder
+import io.kotest.matchers.maps.shouldBeEmpty
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.shouldNotBe
 import kotlin.reflect.typeOf
@@ -32,6 +33,7 @@ class RouteDocumentationMergerTest : StringSpec({
             route.getResponses().also { responses ->
                 responses.getResponses().shouldBeEmpty()
             }
+            route.extensions.shouldBeEmpty()
         }
     }
 
@@ -59,6 +61,7 @@ class RouteDocumentationMergerTest : StringSpec({
                     "a1" to { description = "response a1" }
                     "a2" to { description = "response a1" }
                 }
+                extensions = mapOf("x-custom-field-a" to "value-a")
             },
             route {
                 specName = "test-spec-b"
@@ -82,6 +85,7 @@ class RouteDocumentationMergerTest : StringSpec({
                     "b1" to { description = "response b1" }
                     "b2" to { description = "response b1" }
                 }
+                extensions = mapOf("x-custom-field-b" to "value-b")
             }
         ).also { route ->
             route.specName shouldBe "test-spec-a"
@@ -115,6 +119,10 @@ class RouteDocumentationMergerTest : StringSpec({
                     "b1", "b2", "a1", "a2"
                 )
             }
+            route.extensions.toList() shouldContainExactlyInAnyOrder listOf(
+                "x-custom-field-a" to "value-a",
+                "x-custom-field-b" to "value-b",
+            )
         }
     }