doc: example header parameter (#114)

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.11.1] - November 25th, 2021
+### Added
+- Documentation showing how to add header names using Kotlin backtick convention
+
 ## [1.11.0] - November 25th, 2021
 ### Added
 - Support for Ktor Location Plugin

README.md

@@ -109,6 +109,14 @@ of camel).
 The purpose of `KompendiumParam` is to provide supplemental information needed to properly assign the type of parameter
 (cookie, header, query, path) as well as other parameter-level metadata.
 
+Using backticks, users can use data classes to represent things like header names as follows
+
+```kotlin
+data class HeaderNameTest(
+  @KompendiumParam(type = ParamType.HEADER) val `X-UserEmail`: String
+)
+```
+
 ### Undeclared Field
 
 There is also a final `UndeclaredField` annotation. This should be used only in an absolutely emergency. This annotation

gradle.properties

@@ -1,5 +1,5 @@
 # Kompendium
-project.version=1.11.0
+project.version=1.11.1
 # Kotlin
 kotlin.code.style=official
 # Gradle

kompendium-core/src/main/kotlin/io/bkbn/kompendium/annotations/KompendiumParam.kt

@@ -1,5 +1,10 @@
 package io.bkbn.kompendium.annotations
 
+/**
+ * Used to indicate that a field in a data class represents an OpenAPI parameter
+ * @param type The type of parameter, must be valid [ParamType]
+ * @param description Description of the parameter to include in OpenAPI Spec
+ */
 @Retention(AnnotationRetention.RUNTIME)
 @Target(AnnotationTarget.PROPERTY)
 annotation class KompendiumParam(val type: ParamType, val description: String = "")

kompendium-core/src/test/kotlin/io/bkbn/kompendium/KompendiumTest.kt

@@ -22,6 +22,7 @@ import io.bkbn.kompendium.util.jacksonConfigModule
 import io.bkbn.kompendium.util.emptyGet
 import io.bkbn.kompendium.util.genericPolymorphicResponse
 import io.bkbn.kompendium.util.genericPolymorphicResponseMultipleImpls
+import io.bkbn.kompendium.util.headerParameter
 import io.bkbn.kompendium.util.kotlinxConfigModule
 import io.bkbn.kompendium.util.nestedUnderRootModule
 import io.bkbn.kompendium.util.nonRequiredParamsGet
@@ -589,6 +590,22 @@ internal class KompendiumTest {
     }
   }
 
+  @Test
+  fun `Can add a custom header parameter with a name override`() {
+    withTestApplication({
+      jacksonConfigModule()
+      docs()
+      headerParameter()
+    }) {
+      // do
+      val json = handleRequest(HttpMethod.Get, "/openapi.json").response.content
+
+      // expect
+      val expected = getFileSnapshot("override_parameter_name.json").trim()
+      assertEquals(expected, json, "The received json spec should match the expected content")
+    }
+  }
+
   private val oas = Kompendium.openApiSpec.copy(
     info = OpenApiSpecInfo(
       title = "Test API",

kompendium-core/src/test/kotlin/io/bkbn/kompendium/util/TestModels.kt

@@ -105,3 +105,7 @@ enum class Hehe {
 
 @UndeclaredField("nowYouDont", Hehe::class)
 data class Mysterious(val nowYouSeeMe: String)
+
+data class HeaderNameTest(
+  @KompendiumParam(type = ParamType.HEADER) val `X-UserEmail`: String
+)

kompendium-core/src/test/kotlin/io/bkbn/kompendium/util/TestModules.kt

@@ -362,6 +362,16 @@ fun Application.undeclaredType() {
   }
 }
 
+fun Application.headerParameter() {
+  routing {
+    route("/test/with_header") {
+      notarizedGet(TestResponseInfo.headerParam) {
+        call.respond(HttpStatusCode.OK, TestResponse("hi"))
+      }
+    }
+  }
+}
+
 fun Application.simpleGenericResponse() {
   routing {
     route("/test/polymorphic") {

kompendium-core/src/test/kotlin/io/bkbn/kompendium/util/TestResponseInfo.kt

@@ -108,6 +108,11 @@ object TestResponseInfo {
     description = "break this glass in scenario of emergency",
     responseInfo = simpleOkResponse()
   )
+  val headerParam = GetInfo<HeaderNameTest, TestResponse>(
+    summary = "testing header stuffs",
+    description = "Good for many things",
+    responseInfo = simpleOkResponse()
+  )
   val genericResponse = GetInfo<Unit, TestGeneric<Int>>(
     summary = "Single Generic",
     description = "Simple generic data class",

kompendium-core/src/test/resources/override_parameter_name.json

@@ -0,0 +1,74 @@
+{
+  "openapi" : "3.0.3",
+  "info" : {
+    "title" : "Test API",
+    "version" : "1.33.7",
+    "description" : "An amazing, fully-ish 😉 generated API spec",
+    "termsOfService" : "https://example.com",
+    "contact" : {
+      "name" : "Homer Simpson",
+      "url" : "https://gph.is/1NPUDiM",
+      "email" : "chunkylover53@aol.com"
+    },
+    "license" : {
+      "name" : "MIT",
+      "url" : "https://github.com/bkbnio/kompendium/blob/main/LICENSE"
+    }
+  },
+  "servers" : [ {
+    "url" : "https://myawesomeapi.com",
+    "description" : "Production instance of my API"
+  }, {
+    "url" : "https://staging.myawesomeapi.com",
+    "description" : "Where the fun stuff happens"
+  } ],
+  "paths" : {
+    "/test/with_header" : {
+      "get" : {
+        "tags" : [ ],
+        "summary" : "testing header stuffs",
+        "description" : "Good for many things",
+        "parameters" : [ {
+          "name" : "X-UserEmail",
+          "in" : "header",
+          "schema" : {
+            "type" : "string"
+          },
+          "required" : true,
+          "deprecated" : false
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "A successful endeavor",
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/TestResponse"
+                }
+              }
+            }
+          }
+        },
+        "deprecated" : false
+      }
+    }
+  },
+  "components" : {
+    "schemas" : {
+      "String" : {
+        "type" : "string"
+      },
+      "TestResponse" : {
+        "type" : "object",
+        "properties" : {
+          "c" : {
+            "$ref" : "#/components/schemas/String"
+          }
+        }
+      }
+    },
+    "securitySchemes" : { }
+  },
+  "security" : [ ],
+  "tags" : [ ]
+}