Merge pull request #43 from AlbRoehm/add-support-for-empty-response

tabilzad · web-flow · commit a32f634f8c64 · 2025-01-25T20:16:06.000-05:00
feat: add empty response body support
diff --git a/README.md b/README.md
@@ -146,6 +146,7 @@ fun Route.ordersRouting() {
 
 ### Responses
 Defining response schemas and their corresponding HTTP status codes are done via `@KtorResponds` annotation on an endpoint. 
+`Nothing` is treated specially and will result in empty response body.
 
 ```kotlin
 @GenerateOpenApi
@@ -154,6 +155,7 @@ fun Route.ordersRouting() {
         @KtorResponds(
                [
                    ResponseEntry("200", Order::class, description = "Created order"),
+                   ResponseEntry("204", Nothing::class),
                    ResponseEntry("400", ErrorResponseSample::class, description = "Invalid order payload")
                ]
         )
diff --git a/create-plugin/src/main/kotlin/io/github/tabilzad/ktor/FileUtils.kt b/create-plugin/src/main/kotlin/io/github/tabilzad/ktor/FileUtils.kt
@@ -25,6 +25,7 @@ internal fun OpenApiSpec.serializeAndWriteTo(configuration: PluginConfiguration)
         val sorted = new.copy(
             components = new.components.copy(
                 schemas = new.components.schemas.toSortedMap()
+                    .filter { (key, value) -> key != "kotlin.Nothing" }
                     .mapValues {
                         it.value.copy(properties = it.value.properties?.toSortedMap())
                     }
diff --git a/create-plugin/src/main/kotlin/io/github/tabilzad/ktor/k2/ExpressionsVisitorK2.kt b/create-plugin/src/main/kotlin/io/github/tabilzad/ktor/k2/ExpressionsVisitorK2.kt
@@ -268,38 +268,44 @@ internal class ExpressionsVisitorK2(
                                 type = kotlinType.toString().toSwaggerType()
                             )
                         } else {
-
                             val typeRef = response.type?.generateTypeAndVisitMemberDescriptors()
                             OpenApiSpec.SchemaType(
                                 `$ref` = "${typeRef?.contentBodyRef}"
                             )
                         }
                     if (!response.isCollection) {
-                        response.status to
+                        if (kotlinType?.isNothing ?: false) {
+                            response.status to OpenApiSpec.ResponseDetails(
+                                response.descr,
+                                null,
+                            )
+                        } else {
+                            response.status to
                                 OpenApiSpec.ResponseDetails(
-                                    response.descr ?: "",
+                                    response.descr,
                                     mapOf(
                                         ContentType.APPLICATION_JSON to mapOf(
                                             "schema" to schema
                                         )
                                     )
                                 )
+                        }
                     } else {
                         response.status to
-                                OpenApiSpec.ResponseDetails(
-                                    response.descr ?: "",
-                                    mapOf(
-                                        ContentType.APPLICATION_JSON to mapOf(
-                                            "schema" to OpenApiSpec.SchemaType(
-                                                type = "array",
-                                                items = OpenApiSpec.SchemaRef(
-                                                    type = schema.type,
-                                                    `$ref` = schema.`$ref`
-                                                )
+                            OpenApiSpec.ResponseDetails(
+                                response.descr,
+                                mapOf(
+                                    ContentType.APPLICATION_JSON to mapOf(
+                                        "schema" to OpenApiSpec.SchemaType(
+                                            type = "array",
+                                            items = OpenApiSpec.SchemaRef(
+                                                type = schema.type,
+                                                `$ref` = schema.`$ref`
                                             )
                                         )
                                     )
                                 )
+                            )
                     }
                 }
 
diff --git a/create-plugin/src/main/kotlin/io/github/tabilzad/ktor/output/OpenApiSpec.kt b/create-plugin/src/main/kotlin/io/github/tabilzad/ktor/output/OpenApiSpec.kt
@@ -85,7 +85,7 @@ data class OpenApiSpec(
 
     data class ResponseDetails(
         val description: String,
-        val content: BodyContent
+        val content: BodyContent?
     )
 
     data class OpenApiComponents(
diff --git a/create-plugin/src/test/kotlin/io/github/tabilzad/ktor/K2StabilityTest.kt b/create-plugin/src/test/kotlin/io/github/tabilzad/ktor/K2StabilityTest.kt
@@ -310,6 +310,18 @@ class K2StabilityTest {
         result.assertWith(expected)
     }
 
+    @Test
+    fun `should correctly resolve Nothing class into empty response annotations`() {
+        val (source, expected) = loadSourceAndExpected("ResponseBodyEmpty")
+        generateCompilerTest(
+            testFile,
+            source,
+            PluginConfiguration.createDefault(hideTransients = false, hidePrivateFields = false)
+        )
+        val result = testFile.readText()
+        result.assertWith(expected)
+    }
+
     @Test
     fun `should handle abstract or sealed schema definitions`() {
         val (source, expected) = loadSourceAndExpected("Abstractions")
diff --git a/create-plugin/src/test/resources/expected/ResponseBodyEmpty-expected.json b/create-plugin/src/test/resources/expected/ResponseBodyEmpty-expected.json
@@ -0,0 +1,92 @@
+{
+  "openapi" : "3.1.0",
+  "info" : {
+    "title" : "Open API Specification",
+    "description" : "test",
+    "version" : "1.0.0"
+  },
+  "paths" : {
+    "/v1/noResponseBody" : {
+      "post" : {
+        "responses" : {
+          "200" : {
+            "description" : "Success"
+          },
+          "500" : {
+            "description" : "Failure",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/sources.requests.PrivateBodyRequest"
+                }
+              }
+            }
+          }
+        },
+        "requestBody" : {
+          "required" : true,
+          "content" : {
+            "application/json" : {
+              "schema" : {
+                "$ref" : "#/components/schemas/sources.requests.SimpleRequest"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/implicitArgNames" : {
+      "post" : {
+        "responses" : {
+          "204" : {
+            "description" : ""
+          }
+        },
+        "requestBody" : {
+          "required" : true,
+          "content" : {
+            "application/json" : {
+              "schema" : {
+                "$ref" : "#/components/schemas/sources.requests.SimpleRequest"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components" : {
+    "schemas" : {
+      "sources.requests.PrivateBodyRequest" : {
+        "type" : "object",
+        "properties" : {
+          "invisible" : {
+            "type" : "string"
+          },
+          "transientFieldInvisible" : {
+            "type" : "integer"
+          },
+          "visible" : {
+            "type" : "boolean"
+          }
+        },
+        "required" : [ "visible", "invisible", "transientFieldInvisible" ]
+      },
+      "sources.requests.SimpleRequest" : {
+        "type" : "object",
+        "properties" : {
+          "float" : {
+            "type" : "number"
+          },
+          "integer" : {
+            "type" : "integer"
+          },
+          "string" : {
+            "type" : "string"
+          }
+        },
+        "required" : [ "string", "integer", "float" ]
+      }
+    }
+  }
+}
diff --git a/create-plugin/src/test/resources/sources/ResponseBodyEmpty.kt b/create-plugin/src/test/resources/sources/ResponseBodyEmpty.kt
@@ -0,0 +1,34 @@
+package sources
+
+import io.github.tabilzad.ktor.annotations.GenerateOpenApi
+import io.github.tabilzad.ktor.annotations.KtorResponds
+import io.github.tabilzad.ktor.annotations.ResponseEntry
+import io.ktor.http.*
+import io.ktor.server.application.*
+import io.ktor.server.request.*
+import io.ktor.server.response.*
+import io.ktor.server.routing.*
+import sources.requests.PrivateBodyRequest
+import sources.requests.SimpleRequest
+
+@GenerateOpenApi
+fun Application.responseBodySample() {
+    routing {
+        route("/v1") {
+            @KtorResponds(
+                mapping = [
+                    ResponseEntry("200", Nothing::class, description = "Success"),
+                    ResponseEntry("500", PrivateBodyRequest::class, description = "Failure")
+                ]
+            )
+            post("/noResponseBody") {
+                call.receive<SimpleRequest>()
+            }
+
+            @KtorResponds([ResponseEntry("204", Nothing::class)])
+            post("/implicitArgNames") {
+                call.receive<SimpleRequest>()
+            }
+        }
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -146,6 +146,7 @@ fun Route.ordersRouting() {`
`146`	`146`
`147`	`147`	`### Responses`
`148`	`148`	Defining response schemas and their corresponding HTTP status codes are done via `@KtorResponds` annotation on an endpoint.
	`149`	+`Nothing` is treated specially and will result in empty response body.
`149`	`150`
`150`	`151`	```kotlin
`151`	`152`	`@GenerateOpenApi`
`@@ -154,6 +155,7 @@ fun Route.ordersRouting() {`
`154`	`155`	`@KtorResponds(`
`155`	`156`	`[`
`156`	`157`	`ResponseEntry("200", Order::class, description = "Created order"),`
	`158`	`+ ResponseEntry("204", Nothing::class),`
`157`	`159`	`ResponseEntry("400", ErrorResponseSample::class, description = "Invalid order payload")`
`158`	`160`	`]`
`159`	`161`	`)`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,7 @@ internal fun OpenApiSpec.serializeAndWriteTo(configuration: PluginConfiguration)`
`25`	`25`	`val sorted = new.copy(`
`26`	`26`	`components = new.components.copy(`
`27`	`27`	`schemas = new.components.schemas.toSortedMap()`
	`28`	`+ .filter { (key, value) -> key != "kotlin.Nothing" }`
`28`	`29`	`.mapValues {`
`29`	`30`	`it.value.copy(properties = it.value.properties?.toSortedMap())`
`30`	`31`	`}`
Original file line number	Diff line number	Diff line change
`@@ -268,38 +268,44 @@ internal class ExpressionsVisitorK2(`
`268`	`268`	`type = kotlinType.toString().toSwaggerType()`
`269`	`269`	`)`
`270`	`270`	`} else {`
`271`		`-`
`272`	`271`	`val typeRef = response.type?.generateTypeAndVisitMemberDescriptors()`
`273`	`272`	`OpenApiSpec.SchemaType(`
`274`	`273`	`$ref` = "${typeRef?.contentBodyRef}"
`275`	`274`	`)`
`276`	`275`	`}`
`277`	`276`	`if (!response.isCollection) {`
`278`		`- response.status to`
	`277`	`+ if (kotlinType?.isNothing ?: false) {`
	`278`	`+ response.status to OpenApiSpec.ResponseDetails(`
	`279`	`+ response.descr,`
	`280`	`+ null,`
	`281`	`+ )`
	`282`	`+ } else {`
	`283`	`+ response.status to`
`279`	`284`	`OpenApiSpec.ResponseDetails(`
`280`		`- response.descr ?: "",`
	`285`	`+ response.descr,`
`281`	`286`	`mapOf(`
`282`	`287`	`ContentType.APPLICATION_JSON to mapOf(`
`283`	`288`	`"schema" to schema`
`284`	`289`	`)`
`285`	`290`	`)`
`286`	`291`	`)`
	`292`	`+ }`
`287`	`293`	`} else {`
`288`	`294`	`response.status to`
`289`		`- OpenApiSpec.ResponseDetails(`
`290`		`- response.descr ?: "",`
`291`		`- mapOf(`
`292`		`- ContentType.APPLICATION_JSON to mapOf(`
`293`		`- "schema" to OpenApiSpec.SchemaType(`
`294`		`- type = "array",`
`295`		`- items = OpenApiSpec.SchemaRef(`
`296`		`- type = schema.type,`
`297`		- `$ref` = schema.`$ref`
`298`		`- )`
	`295`	`+ OpenApiSpec.ResponseDetails(`
	`296`	`+ response.descr,`
	`297`	`+ mapOf(`
	`298`	`+ ContentType.APPLICATION_JSON to mapOf(`
	`299`	`+ "schema" to OpenApiSpec.SchemaType(`
	`300`	`+ type = "array",`
	`301`	`+ items = OpenApiSpec.SchemaRef(`
	`302`	`+ type = schema.type,`
	`303`	+ `$ref` = schema.`$ref`
`299`	`304`	`)`
`300`	`305`	`)`
`301`	`306`	`)`
`302`	`307`	`)`
	`308`	`+ )`
`303`	`309`	`}`
`304`	`310`	`}`
`305`	`311`
Original file line number	Diff line number	Diff line change
`@@ -85,7 +85,7 @@ data class OpenApiSpec(`
`85`	`85`
`86`	`86`	`data class ResponseDetails(`
`87`	`87`	`val description: String,`
`88`		`- val content: BodyContent`
	`88`	`+ val content: BodyContent?`
`89`	`89`	`)`
`90`	`90`
`91`	`91`	`data class OpenApiComponents(`