Merge branch 'improve-support-for-typesafe-routing' into pre-release-5-0-0

Author: SMILEY4

examples/build.gradle.kts

@@ -9,6 +9,7 @@ plugins {
 }
 
 repositories {
+    mavenLocal() // todo: remove after releasing schema-kenerator 1.7.0
     mavenCentral()
 }
 
@@ -17,13 +18,16 @@ dependencies {
     implementation(project(":ktor-swagger-ui"))
     implementation(project(":ktor-redoc"))
 
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0")
+
     val versionKtor: String by project
     implementation("io.ktor:ktor-server-netty-jvm:$versionKtor")
     implementation("io.ktor:ktor-server-content-negotiation:$versionKtor")
     implementation("io.ktor:ktor-serialization-jackson:$versionKtor")
     implementation("io.ktor:ktor-server-auth:$versionKtor")
     implementation("io.ktor:ktor-server-call-logging:$versionKtor")
     implementation("io.ktor:ktor-server-test-host:$versionKtor")
+    implementation("io.ktor:ktor-server-resources:$versionKtor")
 
     val versionSchemaKenerator: String by project
     implementation("io.github.smiley4:schema-kenerator-core:$versionSchemaKenerator")

examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/Petstore.kt

@@ -27,6 +27,21 @@ fun main() {
  */
 private fun Application.myModule() {
 
+    data class Pet(
+        val id: Long,
+        val name: String,
+        val tag: String
+    )
+
+    data class NewPet(
+        val name: String,
+        val tag: String
+    )
+
+    data class ErrorModel(
+        val message: String
+    )
+
     install(OpenApi) {
         info {
             title = "Swagger Petstore"
@@ -247,19 +262,4 @@ private fun Application.myModule() {
 
     }
 
-}
-
-private data class Pet(
-    val id: Long,
-    val name: String,
-    val tag: String
-)
-
-private data class NewPet(
-    val name: String,
-    val tag: String
-)
-
-private data class ErrorModel(
-    val message: String
-)
+}

examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/TypesafeRouting.kt

@@ -0,0 +1,136 @@
+package io.github.smiley4.ktoropenapi.examples
+
+import io.github.smiley4.ktoropenapi.OpenApi
+import io.github.smiley4.ktoropenapi.openApi
+import io.github.smiley4.ktoropenapi.resources.delete
+import io.github.smiley4.ktoropenapi.resources.get
+import io.github.smiley4.ktoropenapi.resources.post
+import io.github.smiley4.ktorredoc.redoc
+import io.github.smiley4.ktorswaggerui.swaggerUI
+import io.github.smiley4.schemakenerator.serialization.processKotlinxSerialization
+import io.github.smiley4.schemakenerator.swagger.compileReferencingRoot
+import io.github.smiley4.schemakenerator.swagger.data.TitleType
+import io.github.smiley4.schemakenerator.swagger.generateSwaggerSchema
+import io.github.smiley4.schemakenerator.swagger.handleCoreAnnotations
+import io.github.smiley4.schemakenerator.swagger.withTitle
+import io.ktor.http.HttpStatusCode
+import io.ktor.resources.Resource
+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.resources.Resources
+import io.ktor.server.response.respond
+import io.ktor.server.routing.route
+import io.ktor.server.routing.routing
+import kotlinx.serialization.Serializable
+
+fun main() {
+    embeddedServer(Netty, port = 8080, host = "localhost", module = Application::myModule).start(wait = true)
+}
+
+private fun Application.myModule() {
+
+    install(Resources)
+
+    install(OpenApi) {
+        // enable automatically extracting documentation from resources-routes
+        autoDocumentResourcesRoutes = true
+        // schema-generator must use kotlinx-serialization to be compatible with resources
+        schemas {
+            generator = { type ->
+                type
+                    .processKotlinxSerialization()
+                    .generateSwaggerSchema()
+                    .withTitle(TitleType.SIMPLE)
+                    .handleCoreAnnotations()
+                    .compileReferencingRoot()
+            }
+        }
+    }
+
+    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")
+        }
+
+        // query and path parameters are picked up automatically and added to the schema with the correct name and type
+        get<PetsRoute.All> { request ->
+            println("..${request.tags}, ${request.limit}")
+            call.respond(HttpStatusCode.NotImplemented, Unit)
+        }
+
+        // additional information can be added to the route manually as usual.
+        // automatically added information can also be overwritten this way.
+        get<PetsRoute.Id>({
+            request {
+                pathParameter<Long>("id") {
+                    description = "the id of the pet"
+                }
+            }
+        }) { request ->
+            println("..${request.id}")
+            call.respond(HttpStatusCode.NotImplemented, Unit)
+        }
+
+        delete<PetsRoute.Id.Delete> { request ->
+            println("..${request.parent.id}")
+            call.respond(HttpStatusCode.NotImplemented, Unit)
+        }
+
+        post<PetsRoute.Id.New> { request ->
+            println("..${request.parent.id}")
+            call.respond(HttpStatusCode.NotImplemented, Unit)
+        }
+
+    }
+
+}
+
+
+@Resource("/pets")
+class PetsRoute {
+
+    @Resource("/")
+    class All(
+        val parent: PetsRoute,
+        val tags: List<String>?,
+        val limit: Int = 100
+    )
+
+
+    @Resource("{id}")
+    class Id(
+        val parent: PetsRoute,
+        val id: Long
+    ) {
+
+        @Resource("/")
+        class Delete(
+            val parent: Id
+        )
+
+
+        @Resource("/")
+        class New(
+            val parent: Id,
+        )
+
+    }
+
+}
+
+
+@Serializable
+data class Pet(
+    val name: String,
+    val tag: String
+)

gradle.properties

@@ -16,7 +16,7 @@ projectDeveloperUrl=https://github.com/SMILEY4
 versionKtor=3.0.0
 versionSwaggerUI=5.17.11
 versionSwaggerParser=2.1.24
-versionSchemaKenerator=1.6.3
+versionSchemaKenerator=1.7.0
 versionKotlinLogging=7.0.0
 versionKotest=5.8.0
 versionKotlinTest=2.0.21

ktor-openapi/build.gradle.kts

@@ -19,6 +19,7 @@ plugins {
 
 repositories {
     mavenCentral()
+    mavenLocal() // todo: remove after releasing schema-kenerator 1.7.0
 }
 
 dependencies {
@@ -43,6 +44,7 @@ dependencies {
     val versionSchemaKenerator: String by project
     implementation("io.github.smiley4:schema-kenerator-core:$versionSchemaKenerator")
     implementation("io.github.smiley4:schema-kenerator-reflection:$versionSchemaKenerator")
+    implementation("io.github.smiley4:schema-kenerator-serialization:$versionSchemaKenerator")
     implementation("io.github.smiley4:schema-kenerator-swagger:$versionSchemaKenerator")
 
     val versionKotlinLogging: String by project

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

@@ -9,6 +9,7 @@ import io.github.smiley4.ktoropenapi.config.OpenApiPluginConfig
 import io.ktor.http.ContentType
 import io.ktor.http.HttpStatusCode
 import io.ktor.server.application.Application
+import io.ktor.server.application.ApplicationPlugin
 import io.ktor.server.application.ApplicationStarted
 import io.ktor.server.application.createApplicationPlugin
 import io.ktor.server.application.hooks.MonitoringEvent
@@ -20,7 +21,7 @@ import io.ktor.server.routing.get
 
 private val logger = KotlinLogging.logger {}
 
-val OpenApi = createApplicationPlugin(name = "OpenApi", createConfiguration = ::OpenApiPluginConfig) {
+val OpenApi: ApplicationPlugin<OpenApiPluginConfig> = createApplicationPlugin(name = "OpenApi", createConfiguration = ::OpenApiPluginConfig) {
     OpenApiPlugin.config = pluginConfig.build(OpenApiPluginData.DEFAULT, getRootPath(application))
     on(MonitoringEvent(ApplicationStarted)) { application ->
         try {

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

@@ -24,7 +24,9 @@ internal class OperationBuilder(
             it.operationId = route.documentation.operationId
             it.deprecated = route.documentation.deprecated
             it.tags = operationTagsBuilder.build(route)
-            it.parameters = route.documentation.request.parameters.map { param -> parameterBuilder.build(param) }
+            it.parameters = route.documentation.request.parameters
+                .filter { param -> !param.hidden }
+                .map { param -> parameterBuilder.build(param) }
             route.documentation.request.body?.let { body ->
                 it.requestBody = requestBodyBuilder.build(body)
             }

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

@@ -17,6 +17,7 @@ internal class ResponsesBuilder(
     fun build(responses: List<ResponseData>, isProtected: Boolean): ApiResponses =
         ApiResponses().also {
             responses
+                .filter { !it.hidden }
                 .map { response -> responseBuilder.build(response) }
                 .forEach { (name, response) -> it.addApiResponse(name, response) }
             if (shouldAddUnauthorized(responses, isProtected)) {
@@ -29,6 +30,7 @@ internal class ResponsesBuilder(
     private fun shouldAddUnauthorized(responses: List<ResponseData>, isProtected: Boolean): Boolean {
         val unauthorizedCode = HttpStatusCode.Unauthorized.value.toString()
         return config.securityConfig.defaultUnauthorizedResponse != null
+                && !config.securityConfig.defaultUnauthorizedResponse.hidden
                 && isProtected
                 && responses.count { it.statusCode == unauthorizedCode } == 0
     }

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

@@ -1,8 +1,8 @@
 package io.github.smiley4.ktoropenapi.builder.route
 
-import io.github.smiley4.ktoropenapi.data.OpenApiPluginData
-import io.github.smiley4.ktoropenapi.config.RouteConfig
 import io.github.smiley4.ktoropenapi.DocumentedRouteSelector
+import io.github.smiley4.ktoropenapi.config.RouteConfig
+import io.github.smiley4.ktoropenapi.data.OpenApiPluginData
 import io.ktor.http.HttpMethod
 import io.ktor.server.auth.AuthenticationRouteSelector
 import io.ktor.server.routing.ConstantParameterRouteSelector
@@ -49,6 +49,13 @@ internal class RouteCollector {
             .toList()
     }
 
+    private fun unroll(route: RoutingNode): List<Pair<RoutingNode, RouteSelector>> {
+        return if (route.parent != null) {
+            unroll(route.parent!!) + listOf(route to route.selector)
+        } else {
+            emptyList()
+        }
+    }
 
     private fun getDocumentation(route: RoutingNode, base: RouteConfig): RouteConfig {
         var documentation = base

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

@@ -1,5 +1,7 @@
 package io.github.smiley4.ktoropenapi.builder.route
 
+import io.github.smiley4.ktoropenapi.config.RequestConfig
+import io.github.smiley4.ktoropenapi.config.RequestParameterConfig
 import io.github.smiley4.ktoropenapi.config.RouteConfig
 
 internal class RouteDocumentationMerger {
@@ -10,7 +12,7 @@ internal class RouteDocumentationMerger {
     fun merge(a: RouteConfig, b: RouteConfig): RouteConfig {
         return RouteConfig().apply {
             specName = a.specName ?: b.specName
-            tags = mutableListOf<String>().also {
+            tags = mutableSetOf<String>().also {
                 it.addAll(a.tags)
                 it.addAll(b.tags)
             }
@@ -25,15 +27,17 @@ internal class RouteDocumentationMerger {
             hidden = a.hidden || b.hidden
             protected = a.protected ?: b.protected
             request {
-                parameters.also {
-                    it.addAll(a.getRequest().parameters)
-                    it.addAll(b.getRequest().parameters)
-                }
+                buildMap {
+                    b.getRequest().parameters.forEach { this[it.name] = it }
+                    a.getRequest().parameters.forEach { this[it.name] = it }
+                }.values.forEach { parameters.add(it) }
                 setBody(a.getRequest().getBody() ?: b.getRequest().getBody())
             }
             response {
-                b.getResponses().getResponses().forEach { response -> addResponse(response) }
-                a.getResponses().getResponses().forEach { response -> addResponse(response) }
+                buildMap {
+                    b.getResponses().getResponses().forEach { this[it.statusCode] = it }
+                    a.getResponses().getResponses().forEach { this[it.statusCode] = it }
+                }.values.forEach { addResponse(it) }
             }
         }
     }