feat: add operationId method info (#106)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.10.0] - November 25th, 2021
+
+### Changed
+
+- Added `operationId` parameter to `MethodInfo`
+
 ## [1.9.2] - October 24th, 2021
 
 ### Changed

README.md

@@ -210,6 +210,7 @@ fun Application.mainModule() {
 val simpleGetInfo = GetInfo<Unit, ExampleResponse>(
   summary = "Example Parameters",
   description = "A test for setting parameter examples",
+  operationId = "getExamples",
   responseInfo = ResponseInfo(
     status = 200,
     description = "nice",

gradle.properties

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

kompendium-core/src/main/kotlin/io/bkbn/kompendium/MethodParser.kt

@@ -49,6 +49,7 @@ object MethodParser {
   ) = OpenApiSpecPathItemOperation(
     summary = info.summary,
     description = info.description,
+    operationId = info.operationId,
     tags = info.tags,
     deprecated = info.deprecated,
     parameters = paramType.toParameterSpec(),

kompendium-core/src/main/kotlin/io/bkbn/kompendium/models/meta/MethodInfo.kt

@@ -11,6 +11,7 @@ sealed class MethodInfo<TParam, TResp>(
   open val canThrow: Set<KClass<*>> = emptySet(),
   open val responseInfo: ResponseInfo<TResp>? = null,
   open val parameterExamples: Map<String, TParam> = emptyMap(),
+  open val operationId: String? = null
 ) {
 
   data class GetInfo<TParam, TResp>(
@@ -21,7 +22,8 @@ sealed class MethodInfo<TParam, TResp>(
     override val deprecated: Boolean = false,
     override val securitySchemes: Set<String> = emptySet(),
     override val canThrow: Set<KClass<*>> = emptySet(),
-    override val parameterExamples: Map<String, TParam> = emptyMap()
+    override val parameterExamples: Map<String, TParam> = emptyMap(),
+    override val operationId: String? = null
   ) : MethodInfo<TParam, TResp>(
     summary = summary,
     description = description,
@@ -30,7 +32,8 @@ sealed class MethodInfo<TParam, TResp>(
     securitySchemes = securitySchemes,
     canThrow = canThrow,
     responseInfo = responseInfo,
-    parameterExamples = parameterExamples
+    parameterExamples = parameterExamples,
+    operationId = operationId
   )
 
   data class PostInfo<TParam, TReq, TResp>(
@@ -42,7 +45,8 @@ sealed class MethodInfo<TParam, TResp>(
     override val deprecated: Boolean = false,
     override val securitySchemes: Set<String> = emptySet(),
     override val canThrow: Set<KClass<*>> = emptySet(),
-    override val parameterExamples: Map<String, TParam> = emptyMap()
+    override val parameterExamples: Map<String, TParam> = emptyMap(),
+    override val operationId: String? = null
   ) : MethodInfo<TParam, TResp>(
     summary = summary,
     description = description,
@@ -51,7 +55,8 @@ sealed class MethodInfo<TParam, TResp>(
     securitySchemes = securitySchemes,
     canThrow = canThrow,
     responseInfo = responseInfo,
-    parameterExamples = parameterExamples
+    parameterExamples = parameterExamples,
+    operationId = operationId
   )
 
   data class PutInfo<TParam, TReq, TResp>(
@@ -63,7 +68,8 @@ sealed class MethodInfo<TParam, TResp>(
     override val deprecated: Boolean = false,
     override val securitySchemes: Set<String> = emptySet(),
     override val canThrow: Set<KClass<*>> = emptySet(),
-    override val parameterExamples: Map<String, TParam> = emptyMap()
+    override val parameterExamples: Map<String, TParam> = emptyMap(),
+    override val operationId: String? = null
   ) : MethodInfo<TParam, TResp>(
     summary = summary,
     description = description,
@@ -71,7 +77,8 @@ sealed class MethodInfo<TParam, TResp>(
     deprecated = deprecated,
     securitySchemes = securitySchemes,
     canThrow = canThrow,
-    parameterExamples = parameterExamples
+    parameterExamples = parameterExamples,
+    operationId = operationId
   )
 
   data class DeleteInfo<TParam, TResp>(
@@ -82,7 +89,8 @@ sealed class MethodInfo<TParam, TResp>(
     override val deprecated: Boolean = false,
     override val securitySchemes: Set<String> = emptySet(),
     override val canThrow: Set<KClass<*>> = emptySet(),
-    override val parameterExamples: Map<String, TParam> = emptyMap()
+    override val parameterExamples: Map<String, TParam> = emptyMap(),
+    override val operationId: String? = null
   ) : MethodInfo<TParam, TResp>(
     summary = summary,
     description = description,
@@ -90,6 +98,7 @@ sealed class MethodInfo<TParam, TResp>(
     deprecated = deprecated,
     securitySchemes = securitySchemes,
     canThrow = canThrow,
-    parameterExamples = parameterExamples
+    parameterExamples = parameterExamples,
+    operationId = operationId
   )
 }

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

@@ -46,6 +46,7 @@ import io.bkbn.kompendium.util.trailingSlash
 import io.bkbn.kompendium.util.undeclaredType
 import io.bkbn.kompendium.util.withDefaultParameter
 import io.bkbn.kompendium.util.withExamples
+import io.bkbn.kompendium.util.withOperationId
 
 internal class KompendiumTest {
 
@@ -139,7 +140,6 @@ internal class KompendiumTest {
     }
   }
 
-
   @Test
   fun `Notarized put does not interrupt the pipeline`() {
     withTestApplication({
@@ -363,6 +363,22 @@ internal class KompendiumTest {
     }
   }
 
+  @Test
+  fun `Can add operationId`() {
+    withTestApplication({
+      jacksonConfigModule()
+      docs()
+      withOperationId()
+    }) {
+      // do
+      val json = handleRequest(HttpMethod.Get, "/openapi.json").response.content
+
+      // expect
+      val expected = getFileSnapshot("notarized_get_with_operation_id.json").trim()
+      assertEquals(expected, json, "The received json spec should match the expected content")
+    }
+  }
+
   @Test
   fun `Generates the expected redoc`() {
     withTestApplication({
@@ -607,5 +623,4 @@ internal class KompendiumTest {
       redoc(oas)
     }
   }
-
 }

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

@@ -265,6 +265,18 @@ fun Application.withDefaultParameter() {
   }
 }
 
+fun Application.withOperationId(){
+  routing {
+    route("/test") {
+      notarizedGet(
+        info = TestResponseInfo.testGetInfo.copy(operationId = "getTest")
+      ){
+        call.respond(HttpStatusCode.OK)
+      }
+    }
+  }
+}
+
 fun Application.nonRequiredParamsGet() {
   routing {
     route("/test/optional") {

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

@@ -0,0 +1,88 @@
+{
+  "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" : {
+      "get" : {
+        "tags" : [ ],
+        "summary" : "Another get test",
+        "description" : "testing more",
+        "operationId" : "getTest",
+        "parameters" : [ {
+          "name" : "a",
+          "in" : "path",
+          "schema" : {
+            "type" : "string"
+          },
+          "required" : true,
+          "deprecated" : false
+        }, {
+          "name" : "aa",
+          "in" : "query",
+          "schema" : {
+            "type" : "integer",
+            "format" : "int32"
+          },
+          "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"
+          }
+        }
+      },
+      "Int" : {
+        "type" : "integer",
+        "format" : "int32"
+      }
+    },
+    "securitySchemes" : { }
+  },
+  "security" : [ ],
+  "tags" : [ ]
+}