Merge branch 'support-webhooks' into pre-release-5-0-0

SMILEY4 · SMILEY4 · commit 2ea7d3932e60 · 2025-01-30T00:18:10.000+01:00
diff --git a/examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/TypesafeRouting.kt b/examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/TypesafeRouting.kt
@@ -51,7 +51,7 @@ private fun Application.myModule() {
 
     routing {
 
-        // add the routes for  the api-spec, swagger-ui and redoc
+        // add the routes for the api-spec, swagger-ui and redoc
         route("api.json") {
             openApi()
         }
diff --git a/examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/Webhooks.kt b/examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/Webhooks.kt
@@ -0,0 +1,67 @@
+package io.github.smiley4.ktoropenapi.examples
+
+import io.github.smiley4.ktoropenapi.OpenApi
+import io.github.smiley4.ktoropenapi.openApi
+import io.github.smiley4.ktoropenapi.post
+import io.github.smiley4.ktoropenapi.webhook
+import io.github.smiley4.ktorredoc.redoc
+import io.github.smiley4.ktorswaggerui.swaggerUI
+import io.ktor.http.ContentType
+import io.ktor.http.HttpMethod
+import io.ktor.http.HttpStatusCode
+import io.ktor.server.application.Application
+import io.ktor.server.application.install
+import io.ktor.server.engine.embeddedServer
+import io.ktor.server.netty.Netty
+import io.ktor.server.response.respond
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+
+fun main() {
+    embeddedServer(Netty, port = 8080, host = "localhost", module = Application::myModule).start(wait = true)
+}
+
+private fun Application.myModule() {
+
+    // Install the "OpenApi"-Plugin
+    install(OpenApi)
+
+    routing {
+
+        // add the routes for the api-spec, swagger-ui and redoc
+        route("api.json") {
+            openApi()
+        }
+        route("swagger") {
+            swaggerUI("/api.json")
+        }
+        route("redoc") {
+            redoc("/api.json")
+        }
+
+        // a "normal" documented route to register for notifications
+        post("registerForAlert", {
+            description = "Register an URL to be called when new concerts are scheduled."
+            request {
+                body<String> {
+                    description = "The URL to be notified about approaching concerts."
+                }
+            }
+        }) {
+            call.respond(HttpStatusCode.NotImplemented, Unit)
+        }
+
+        // documentation of the webhook to notify
+        webhook(HttpMethod.Post, "concertAlert") {
+            description = "Notify the registered URL with details of an upcoming concert"
+            request {
+                body<String> {
+                    mediaTypes(ContentType.Text.Plain)
+                    required = true
+                }
+            }
+        }
+
+    }
+
+}
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/DocumentedRouteSelector.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/DocumentedRouteSelector.kt
@@ -301,3 +301,14 @@ fun Route.head(
 ): Route {
     return documentation(builder) { head(body) }
 }
+
+
+//===============================//
+//            WEBHOOK            //
+//===============================//
+
+internal val webhooks = mutableMapOf<String, Pair<HttpMethod, RouteConfig>>()
+
+fun webhook(method: HttpMethod, name: String, builder: RouteConfig.() -> Unit = { },) {
+    webhooks[name] = method to RouteConfig().apply(builder)
+}
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/OpenApiPlugin.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/OpenApiPlugin.kt
@@ -3,10 +3,12 @@ package io.github.smiley4.ktoropenapi
 import io.github.oshai.kotlinlogging.KotlinLogging
 import io.github.smiley4.ktoropenapi.builder.OpenApiSpecBuilder
 import io.github.smiley4.ktoropenapi.builder.route.RouteCollector
+import io.github.smiley4.ktoropenapi.builder.route.RouteMeta
 import io.github.smiley4.ktoropenapi.config.OpenApiPluginConfig
 import io.github.smiley4.ktoropenapi.config.OutputFormat
 import io.github.smiley4.ktoropenapi.data.OpenApiPluginData
 import io.ktor.http.ContentType
+import io.ktor.http.HttpMethod
 import io.ktor.http.HttpStatusCode
 import io.ktor.server.application.Application
 import io.ktor.server.application.ApplicationPlugin
@@ -51,7 +53,15 @@ object OpenApiPlugin {
      * Generates new openapi
      */
     fun generateOpenApiSpecs(application: Application) {
-        val routes = RouteCollector().collect({ application.plugin(RoutingRoot) }, config)
+        val routes = RouteCollector().collect({ application.plugin(RoutingRoot) }, config) + webhooks.map { (name, entry) ->
+            RouteMeta(
+                method = entry.first,
+                path = name,
+                documentation = entry.second.build(),
+                protected = false,
+                isWebhook = true
+            )
+        }
         val specs = OpenApiSpecBuilder().build(config, routes)
         openApiSpecs.clear()
         openApiSpecs.putAll(specs)
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/OpenApiSpecBuilder.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/OpenApiSpecBuilder.kt
@@ -1,6 +1,7 @@
 package io.github.smiley4.ktoropenapi.builder
 
 import io.github.oshai.kotlinlogging.KotlinLogging
+import io.github.smiley4.ktoropenapi.OpenApiPlugin.config
 import io.github.smiley4.ktoropenapi.builder.example.ExampleContext
 import io.github.smiley4.ktoropenapi.builder.example.ExampleContextImpl
 import io.github.smiley4.ktoropenapi.builder.openapi.ComponentsBuilder
@@ -25,6 +26,7 @@ import io.github.smiley4.ktoropenapi.builder.openapi.SecuritySchemesBuilder
 import io.github.smiley4.ktoropenapi.builder.openapi.ServerBuilder
 import io.github.smiley4.ktoropenapi.builder.openapi.TagBuilder
 import io.github.smiley4.ktoropenapi.builder.openapi.TagExternalDocumentationBuilder
+import io.github.smiley4.ktoropenapi.builder.openapi.WebhooksBuilder
 import io.github.smiley4.ktoropenapi.builder.route.RouteMeta
 import io.github.smiley4.ktoropenapi.builder.schema.SchemaContext
 import io.github.smiley4.ktoropenapi.builder.schema.SchemaContextImpl
@@ -88,6 +90,36 @@ internal class OpenApiSpecBuilder {
         schemaContext: SchemaContext,
         exampleContext: ExampleContext,
     ): OpenApiBuilder {
+        val pathBuilder = PathBuilder(
+            operationBuilder = OperationBuilder(
+                operationTagsBuilder = OperationTagsBuilder(config),
+                parameterBuilder = ParameterBuilder(
+                    schemaContext = schemaContext,
+                    exampleContext = exampleContext,
+                ),
+                requestBodyBuilder = RequestBodyBuilder(
+                    contentBuilder = ContentBuilder(
+                        schemaContext = schemaContext,
+                        exampleContext = exampleContext,
+                        headerBuilder = HeaderBuilder(schemaContext)
+                    )
+                ),
+                responsesBuilder = ResponsesBuilder(
+                    responseBuilder = ResponseBuilder(
+                        headerBuilder = HeaderBuilder(schemaContext),
+                        contentBuilder = ContentBuilder(
+                            schemaContext = schemaContext,
+                            exampleContext = exampleContext,
+                            headerBuilder = HeaderBuilder(schemaContext)
+                        )
+                    ),
+                    config = config
+                ),
+                securityRequirementsBuilder = SecurityRequirementsBuilder(config),
+                externalDocumentationBuilder = ExternalDocumentationBuilder(),
+                serverBuilder = ServerBuilder()
+            )
+        )
         return OpenApiBuilder(
             config = config,
             schemaContext = schemaContext,
@@ -103,36 +135,10 @@ internal class OpenApiSpecBuilder {
             ),
             pathsBuilder = PathsBuilder(
                 config = config,
-                pathBuilder = PathBuilder(
-                    operationBuilder = OperationBuilder(
-                        operationTagsBuilder = OperationTagsBuilder(config),
-                        parameterBuilder = ParameterBuilder(
-                            schemaContext = schemaContext,
-                            exampleContext = exampleContext,
-                        ),
-                        requestBodyBuilder = RequestBodyBuilder(
-                            contentBuilder = ContentBuilder(
-                                schemaContext = schemaContext,
-                                exampleContext = exampleContext,
-                                headerBuilder = HeaderBuilder(schemaContext)
-                            )
-                        ),
-                        responsesBuilder = ResponsesBuilder(
-                            responseBuilder = ResponseBuilder(
-                                headerBuilder = HeaderBuilder(schemaContext),
-                                contentBuilder = ContentBuilder(
-                                    schemaContext = schemaContext,
-                                    exampleContext = exampleContext,
-                                    headerBuilder = HeaderBuilder(schemaContext)
-                                )
-                            ),
-                            config = config
-                        ),
-                        securityRequirementsBuilder = SecurityRequirementsBuilder(config),
-                        externalDocumentationBuilder = ExternalDocumentationBuilder(),
-                        serverBuilder = ServerBuilder()
-                    )
-                )
+                pathBuilder = pathBuilder
+            ),
+            webhooksBuilder = WebhooksBuilder(
+                pathBuilder = pathBuilder
             ),
             componentsBuilder = ComponentsBuilder(
                 config = config,
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/openapi/OpenApiBuilder.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/openapi/OpenApiBuilder.kt
@@ -20,6 +20,7 @@ internal class OpenApiBuilder(
     private val serverBuilder: ServerBuilder,
     private val tagBuilder: TagBuilder,
     private val pathsBuilder: PathsBuilder,
+    private val webhooksBuilder: WebhooksBuilder,
     private val componentsBuilder: ComponentsBuilder,
 ) {
 
@@ -31,7 +32,8 @@ internal class OpenApiBuilder(
             it.externalDocs = externalDocumentationBuilder.build(config.externalDocs)
             it.servers = config.servers.map { server -> serverBuilder.build(server) }
             it.tags = config.tagsConfig.tags.map { tag -> tagBuilder.build(tag) }
-            it.paths = pathsBuilder.build(routes)
+            it.paths = pathsBuilder.build(routes.filter { r -> !r.isWebhook})
+            it.webhooks = webhooksBuilder.build(routes.filter { r -> r.isWebhook})
             it.components = componentsBuilder.build(schemaContext.getComponentSection(), exampleContext.getComponentSection())
         }
     }
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/openapi/WebhooksBuilder.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/openapi/WebhooksBuilder.kt
@@ -0,0 +1,20 @@
+package io.github.smiley4.ktoropenapi.builder.openapi
+
+import io.github.smiley4.ktoropenapi.builder.route.RouteMeta
+import io.swagger.v3.oas.models.PathItem
+
+/**
+ * Build the openapi "webhooks" section.
+ * See [OpenAPI Specification - Webhooks](https://spec.openapis.org/oas/v3.1.0.html#oasWebhooks)
+ */
+internal class WebhooksBuilder(
+    private val pathBuilder: PathBuilder
+) {
+
+    fun build(routes: Collection<RouteMeta>): Map<String, PathItem> {
+        return routes.associate { route ->
+            route.path to pathBuilder.build(route)
+        }
+    }
+
+}
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/route/RouteCollector.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/route/RouteCollector.kt
@@ -40,7 +40,8 @@ internal class RouteCollector {
                     method = getMethod(route),
                     path = getPath(route, config),
                     documentation = documentation.build(),
-                    protected = documentation.protected ?: isProtected(route)
+                    protected = documentation.protected ?: isProtected(route),
+                    isWebhook = false
                 )
             }
             .filter { !it.documentation.hidden }
diff --git a/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/route/RouteMeta.kt b/ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/route/RouteMeta.kt
@@ -10,5 +10,6 @@ internal data class RouteMeta(
     val path: String,
     val method: HttpMethod,
     val documentation: RouteData,
-    val protected: Boolean
+    val protected: Boolean,
+    val isWebhook: Boolean,
 )
diff --git a/ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OpenApiBuilderTest.kt b/ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OpenApiBuilderTest.kt
@@ -24,6 +24,7 @@ import io.github.smiley4.ktoropenapi.builder.openapi.SecuritySchemesBuilder
 import io.github.smiley4.ktoropenapi.builder.openapi.ServerBuilder
 import io.github.smiley4.ktoropenapi.builder.openapi.TagBuilder
 import io.github.smiley4.ktoropenapi.builder.openapi.TagExternalDocumentationBuilder
+import io.github.smiley4.ktoropenapi.builder.openapi.WebhooksBuilder
 import io.github.smiley4.ktoropenapi.builder.route.RouteMeta
 import io.github.smiley4.ktoropenapi.builder.schema.SchemaContext
 import io.github.smiley4.ktoropenapi.builder.schema.SchemaContextImpl
@@ -172,6 +173,38 @@ class OpenApiBuilderTest : StringSpec({
                         )
                     )
                 ),
+                webhooksBuilder = WebhooksBuilder(
+                    pathBuilder = PathBuilder(
+                        operationBuilder = OperationBuilder(
+                            operationTagsBuilder = OperationTagsBuilder(pluginConfigData),
+                            parameterBuilder = ParameterBuilder(
+                                schemaContext = schemaContext,
+                                exampleContext = exampleContext
+                            ),
+                            requestBodyBuilder = RequestBodyBuilder(
+                                contentBuilder = ContentBuilder(
+                                    schemaContext = schemaContext,
+                                    exampleContext = exampleContext,
+                                    headerBuilder = HeaderBuilder(schemaContext)
+                                )
+                            ),
+                            responsesBuilder = ResponsesBuilder(
+                                responseBuilder = ResponseBuilder(
+                                    headerBuilder = HeaderBuilder(schemaContext),
+                                    contentBuilder = ContentBuilder(
+                                        schemaContext = schemaContext,
+                                        exampleContext = exampleContext,
+                                        headerBuilder = HeaderBuilder(schemaContext)
+                                    )
+                                ),
+                                config = pluginConfigData
+                            ),
+                            securityRequirementsBuilder = SecurityRequirementsBuilder(pluginConfigData),
+                            externalDocumentationBuilder = ExternalDocumentationBuilder(),
+                            serverBuilder = ServerBuilder()
+                        )
+                    )
+                ),
                 componentsBuilder = ComponentsBuilder(
                     config = pluginConfigData,
                     securitySchemesBuilder = SecuritySchemesBuilder(
diff --git a/ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OperationBuilderTest.kt b/ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OperationBuilderTest.kt
diff --git a/ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/PathsBuilderTest.kt b/ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/PathsBuilderTest.kt

Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ private fun Application.myModule() {`
`51`	`51`
`52`	`52`	`routing {`
`53`	`53`
`54`		`- // add the routes for the api-spec, swagger-ui and redoc`
	`54`	`+ // add the routes for the api-spec, swagger-ui and redoc`
`55`	`55`	`route("api.json") {`
`56`	`56`	`openApi()`
`57`	`57`	`}`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,8 @@ internal class RouteCollector {`
`40`	`40`	`method = getMethod(route),`
`41`	`41`	`path = getPath(route, config),`
`42`	`42`	`documentation = documentation.build(),`
`43`		`- protected = documentation.protected ?: isProtected(route)`
	`43`	`+ protected = documentation.protected ?: isProtected(route),`
	`44`	`+ isWebhook = false`
`44`	`45`	`)`
`45`	`46`	`}`
`46`	`47`	`.filter { !it.documentation.hidden }`
Original file line number	Diff line number	Diff line change
`@@ -10,5 +10,6 @@ internal data class RouteMeta(`
`10`	`10`	`val path: String,`
`11`	`11`	`val method: HttpMethod,`
`12`	`12`	`val documentation: RouteData,`
`13`		`- val protected: Boolean`
	`13`	`+ val protected: Boolean,`
	`14`	`+ val isWebhook: Boolean,`
`14`	`15`	`)`