feat: schema configurator to enable field name overrides and transient field omission (#302)

2022-08-23 13:02:50 +01:00
parent bf31dd213c
commit 07bdeda364
28 changed files with 581 additions and 85 deletions
--- a/core/src/main/kotlin/io/bkbn/kompendium/core/attribute/KompendiumAttributes.kt
+++ b/core/src/main/kotlin/io/bkbn/kompendium/core/attribute/KompendiumAttributes.kt
@ -1,8 +1,10 @@
 package io.bkbn.kompendium.core.attribute

+import io.bkbn.kompendium.json.schema.SchemaConfigurator
 import io.bkbn.kompendium.oas.OpenApiSpec
 import io.ktor.util.AttributeKey

 object KompendiumAttributes {
  val openApiSpec = AttributeKey<OpenApiSpec>("OpenApiSpec")
+  val schemaConfigurator = AttributeKey<SchemaConfigurator>("SchemaConfigurator")
 }
--- a/core/src/main/kotlin/io/bkbn/kompendium/core/plugin/NotarizedApplication.kt
+++ b/core/src/main/kotlin/io/bkbn/kompendium/core/plugin/NotarizedApplication.kt
@ -1,6 +1,7 @@
 package io.bkbn.kompendium.core.plugin

 import io.bkbn.kompendium.core.attribute.KompendiumAttributes
+import io.bkbn.kompendium.json.schema.SchemaConfigurator
 import io.bkbn.kompendium.json.schema.definition.JsonSchema
 import io.bkbn.kompendium.json.schema.util.Helpers.getSimpleSlug
 import io.bkbn.kompendium.oas.OpenApiSpec
@ -13,7 +14,6 @@ import io.ktor.server.routing.application
 import io.ktor.server.routing.get
 import io.ktor.server.routing.route
 import io.ktor.server.routing.routing
-import kotlin.reflect.KClass
 import kotlin.reflect.KType

 object NotarizedApplication {
@ -28,6 +28,7 @@ object NotarizedApplication {
      }
    }
    var customTypes: Map<KType, JsonSchema> = emptyMap()
+    var schemaConfigurator: SchemaConfigurator = SchemaConfigurator.Default()
  }

  operator fun invoke() = createApplicationPlugin(
@ -41,5 +42,6 @@ object NotarizedApplication {
      spec.components.schemas[type.getSimpleSlug()] = schema
    }
    application.attributes.put(KompendiumAttributes.openApiSpec, spec)
+    application.attributes.put(KompendiumAttributes.schemaConfigurator, pluginConfig.schemaConfigurator)
  }
 }
--- a/core/src/main/kotlin/io/bkbn/kompendium/core/plugin/NotarizedRoute.kt
+++ b/core/src/main/kotlin/io/bkbn/kompendium/core/plugin/NotarizedRoute.kt
@ -63,17 +63,18 @@ object NotarizedRoute {
    }

    val spec = application.attributes[KompendiumAttributes.openApiSpec]
+    val serializableReader = application.attributes[KompendiumAttributes.schemaConfigurator]

    val path = Path()
    path.parameters = pluginConfig.parameters

-    pluginConfig.get?.addToSpec(path, spec, pluginConfig)
-    pluginConfig.delete?.addToSpec(path, spec, pluginConfig)
-    pluginConfig.head?.addToSpec(path, spec, pluginConfig)
-    pluginConfig.options?.addToSpec(path, spec, pluginConfig)
-    pluginConfig.post?.addToSpec(path, spec, pluginConfig)
-    pluginConfig.put?.addToSpec(path, spec, pluginConfig)
-    pluginConfig.patch?.addToSpec(path, spec, pluginConfig)
+    pluginConfig.get?.addToSpec(path, spec, pluginConfig, serializableReader)
+    pluginConfig.delete?.addToSpec(path, spec, pluginConfig, serializableReader)
+    pluginConfig.head?.addToSpec(path, spec, pluginConfig, serializableReader)
+    pluginConfig.options?.addToSpec(path, spec, pluginConfig, serializableReader)
+    pluginConfig.post?.addToSpec(path, spec, pluginConfig, serializableReader)
+    pluginConfig.put?.addToSpec(path, spec, pluginConfig, serializableReader)
+    pluginConfig.patch?.addToSpec(path, spec, pluginConfig, serializableReader)

    pluginConfig.path = path
  }
--- a/core/src/main/kotlin/io/bkbn/kompendium/core/util/Helpers.kt
+++ b/core/src/main/kotlin/io/bkbn/kompendium/core/util/Helpers.kt
@ -11,6 +11,7 @@ import io.bkbn.kompendium.core.metadata.PostInfo
 import io.bkbn.kompendium.core.metadata.PutInfo
 import io.bkbn.kompendium.core.metadata.ResponseInfo
 import io.bkbn.kompendium.json.schema.SchemaGenerator
+import io.bkbn.kompendium.json.schema.SchemaConfigurator
 import io.bkbn.kompendium.json.schema.definition.ReferenceDefinition
 import io.bkbn.kompendium.json.schema.util.Helpers.getReferenceSlug
 import io.bkbn.kompendium.json.schema.util.Helpers.getSimpleSlug
@ -25,20 +26,27 @@ import kotlin.reflect.KType

 object Helpers {

-  fun MethodInfo.addToSpec(path: Path, spec: OpenApiSpec, config: SpecConfig) {
-    SchemaGenerator.fromTypeOrUnit(this.response.responseType, spec.components.schemas)?.let { schema ->
+  fun MethodInfo.addToSpec(path: Path, spec: OpenApiSpec, config: SpecConfig, schemaConfigurator: SchemaConfigurator) {
+    SchemaGenerator.fromTypeOrUnit(
+      this.response.responseType,
+      spec.components.schemas, schemaConfigurator
+    )?.let { schema ->
      spec.components.schemas[this.response.responseType.getSimpleSlug()] = schema
    }

    errors.forEach { error ->
-      SchemaGenerator.fromTypeOrUnit(error.responseType, spec.components.schemas)?.let { schema ->
+      SchemaGenerator.fromTypeOrUnit(error.responseType, spec.components.schemas, schemaConfigurator)?.let { schema ->
        spec.components.schemas[error.responseType.getSimpleSlug()] = schema
      }
    }

    when (this) {
      is MethodInfoWithRequest -> {
-        SchemaGenerator.fromTypeOrUnit(this.request.requestType, spec.components.schemas)?.let { schema ->
+        SchemaGenerator.fromTypeOrUnit(
+          this.request.requestType,
+          spec.components.schemas,
+          schemaConfigurator
+        )?.let { schema ->
          spec.components.schemas[this.request.requestType.getSimpleSlug()] = schema
        }
      }
--- a/core/src/test/kotlin/io/bkbn/kompendium/core/KompendiumTest.kt
+++ b/core/src/test/kotlin/io/bkbn/kompendium/core/KompendiumTest.kt
@ -4,6 +4,7 @@ import dev.forst.ktor.apikey.apiKey
 import io.bkbn.kompendium.core.fixtures.TestHelpers.openApiTestAllSerializers
 import io.bkbn.kompendium.core.util.TestModules.complexRequest
 import io.bkbn.kompendium.core.util.TestModules.customAuthConfig
+import io.bkbn.kompendium.core.util.TestModules.customFieldNameResponse
 import io.bkbn.kompendium.core.util.TestModules.dateTimeString
 import io.bkbn.kompendium.core.util.TestModules.defaultAuthConfig
 import io.bkbn.kompendium.core.util.TestModules.defaultField
@ -19,6 +20,7 @@ import io.bkbn.kompendium.core.util.TestModules.genericPolymorphicResponse
 import io.bkbn.kompendium.core.util.TestModules.genericPolymorphicResponseMultipleImpls
 import io.bkbn.kompendium.core.util.TestModules.gnarlyGenericResponse
 import io.bkbn.kompendium.core.util.TestModules.headerParameter
+import io.bkbn.kompendium.core.util.TestModules.ignoredFieldsResponse
 import io.bkbn.kompendium.core.util.TestModules.multipleAuthStrategies
 import io.bkbn.kompendium.core.util.TestModules.multipleExceptions
 import io.bkbn.kompendium.core.util.TestModules.nestedGenericCollection
@ -48,6 +50,7 @@ import io.bkbn.kompendium.core.util.TestModules.simpleGenericResponse
 import io.bkbn.kompendium.core.util.TestModules.simplePathParsing
 import io.bkbn.kompendium.core.util.TestModules.simpleRecursive
 import io.bkbn.kompendium.core.util.TestModules.trailingSlash
+import io.bkbn.kompendium.core.util.TestModules.unbackedFieldsResponse
 import io.bkbn.kompendium.core.util.TestModules.withOperationId
 import io.bkbn.kompendium.json.schema.definition.TypeDefinition
 import io.bkbn.kompendium.oas.component.Components
@ -192,6 +195,17 @@ class KompendiumTest : DescribeSpec({
      openApiTestAllSerializers("T0043__gnarly_generic_example.json") { gnarlyGenericResponse() }
    }
  }
+  describe("Custom Serializable Reader tests") {
+    it("Can support ignoring fields") {
+      openApiTestAllSerializers("T0048__ignored_property.json") { ignoredFieldsResponse() }
+    }
+    it("Can support un-backed fields") {
+      openApiTestAllSerializers("T0049__unbacked_property.json") { unbackedFieldsResponse() }
+    }
+    it("Can support custom named fields") {
+      openApiTestAllSerializers("T0050__custom_named_property.json") { customFieldNameResponse() }
+    }
+  }
  describe("Miscellaneous") {
    xit("Can generate the necessary ReDoc home page") {
      // TODO apiFunctionalityTest(getFileSnapshot("redoc.html"), "/docs") { returnsList() }
--- a/core/src/test/kotlin/io/bkbn/kompendium/core/util/TestModules.kt
+++ b/core/src/test/kotlin/io/bkbn/kompendium/core/util/TestModules.kt
@ -1,27 +1,6 @@
 package io.bkbn.kompendium.core.util

-import io.bkbn.kompendium.core.fixtures.Barzo
-import io.bkbn.kompendium.core.fixtures.ColumnSchema
-import io.bkbn.kompendium.core.fixtures.ComplexRequest
-import io.bkbn.kompendium.core.fixtures.DateTimeString
-import io.bkbn.kompendium.core.fixtures.DefaultField
-import io.bkbn.kompendium.core.fixtures.ExceptionResponse
-import io.bkbn.kompendium.core.fixtures.Flibbity
-import io.bkbn.kompendium.core.fixtures.FlibbityGibbit
-import io.bkbn.kompendium.core.fixtures.Foosy
-import io.bkbn.kompendium.core.fixtures.Gibbity
-import io.bkbn.kompendium.core.fixtures.ManyThings
-import io.bkbn.kompendium.core.fixtures.MultiNestedGenerics
-import io.bkbn.kompendium.core.fixtures.Nested
-import io.bkbn.kompendium.core.fixtures.NullableEnum
-import io.bkbn.kompendium.core.fixtures.NullableField
-import io.bkbn.kompendium.core.fixtures.Page
-import io.bkbn.kompendium.core.fixtures.ProfileUpdateRequest
-import io.bkbn.kompendium.core.fixtures.TestCreatedResponse
-import io.bkbn.kompendium.core.fixtures.TestNested
-import io.bkbn.kompendium.core.fixtures.TestRequest
-import io.bkbn.kompendium.core.fixtures.TestResponse
-import io.bkbn.kompendium.core.fixtures.TestSimpleRequest
+import io.bkbn.kompendium.core.fixtures.*
 import io.bkbn.kompendium.core.metadata.DeleteInfo
 import io.bkbn.kompendium.core.metadata.GetInfo
 import io.bkbn.kompendium.core.metadata.HeadInfo
@ -563,6 +542,12 @@ object TestModules {

  fun Routing.polymorphicResponse() = basicGetGenerator<FlibbityGibbit>()

+  fun Routing.ignoredFieldsResponse() = basicGetGenerator<TransientObject>()
+
+  fun Routing.unbackedFieldsResponse() = basicGetGenerator<UnbakcedObject>()
+
+  fun Routing.customFieldNameResponse() = basicGetGenerator<SerialNameObject>()
+
  fun Routing.polymorphicCollectionResponse() = basicGetGenerator<List<FlibbityGibbit>>()

  fun Routing.polymorphicMapResponse() = basicGetGenerator<Map<String, FlibbityGibbit>>()
--- a/core/src/test/resources/T0048__ignored_property.json
+++ b/core/src/test/resources/T0048__ignored_property.json
@ -0,0 +1,72 @@
+{
+  "openapi": "3.1.0",
+  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+  "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": {
+    "/": {
+      "get": {
+        "tags": [],
+        "summary": "Great Summary!",
+        "description": "testing more",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A Successful Endeavor",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TransientObject"
+                }
+              }
+            }
+          }
+        },
+        "deprecated": false
+      },
+      "parameters": []
+    }
+  },
+  "webhooks": {},
+  "components": {
+    "schemas": {
+      "TransientObject": {
+        "type": "object",
+        "properties": {
+          "nonTransient": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "nonTransient"
+        ]
+      }
+    },
+    "securitySchemes": {}
+  },
+  "security": [],
+  "tags": []
+}
--- a/core/src/test/resources/T0049__unbacked_property.json
+++ b/core/src/test/resources/T0049__unbacked_property.json
@ -0,0 +1,72 @@
+{
+  "openapi": "3.1.0",
+  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+  "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": {
+    "/": {
+      "get": {
+        "tags": [],
+        "summary": "Great Summary!",
+        "description": "testing more",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A Successful Endeavor",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnbakcedObject"
+                }
+              }
+            }
+          }
+        },
+        "deprecated": false
+      },
+      "parameters": []
+    }
+  },
+  "webhooks": {},
+  "components": {
+    "schemas": {
+      "UnbakcedObject": {
+        "type": "object",
+        "properties": {
+          "backed": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "backed"
+        ]
+      }
+    },
+    "securitySchemes": {}
+  },
+  "security": [],
+  "tags": []
+}
--- a/core/src/test/resources/T0050__custom_named_property.json
+++ b/core/src/test/resources/T0050__custom_named_property.json
@ -0,0 +1,72 @@
+{
+  "openapi": "3.1.0",
+  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+  "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": {
+    "/": {
+      "get": {
+        "tags": [],
+        "summary": "Great Summary!",
+        "description": "testing more",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "A Successful Endeavor",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SerialNameObject"
+                }
+              }
+            }
+          }
+        },
+        "deprecated": false
+      },
+      "parameters": []
+    }
+  },
+  "webhooks": {},
+  "components": {
+    "schemas": {
+      "SerialNameObject": {
+        "type": "object",
+        "properties": {
+          "snake_case_name": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "snake_case_name"
+        ]
+      }
+    },
+    "securitySchemes": {}
+  },
+  "security": [],
+  "tags": []
+}
--- a/core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/SchemaConfigurators.kt
+++ b/core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/SchemaConfigurators.kt
@ -0,0 +1,54 @@
+package io.bkbn.kompendium.core.fixtures
+
+import com.fasterxml.jackson.annotation.JsonIgnore
+import com.fasterxml.jackson.annotation.JsonProperty
+import com.google.gson.annotations.Expose
+import com.google.gson.annotations.SerializedName
+import io.bkbn.kompendium.json.schema.SchemaConfigurator
+import kotlin.reflect.KClass
+import kotlin.reflect.KProperty1
+import kotlin.reflect.full.memberProperties
+import kotlin.reflect.jvm.javaField
+
+/*
+  These are test implementation and may well be a good starting point for creating production ones.
+  Both Gson and Jackson are complex and can achieve this things is more than one way therefore
+  these will not always work hence why they are in the test package
+ */
+
+class GsonSchemaConfigurator: SchemaConfigurator {
+
+  override fun serializableMemberProperties(clazz: KClass<*>): Collection<KProperty1<out Any, *>> {
+    // NOTE: This is test logic Expose is set at a global Gson level so configure to match your Gson set up
+    val hasAnyExpose = clazz.memberProperties.any { it.hasJavaAnnotation<Expose>() }
+    return if(hasAnyExpose) {
+      clazz.memberProperties
+        .filter { it.hasJavaAnnotation<Expose>() }
+    } else clazz.memberProperties
+  }
+
+  override fun serializableName(property: KProperty1<out Any, *>): String =
+    property.getJavaAnnotation<SerializedName>()?.value?: property.name
+
+}
+
+class JacksonSchemaConfigurator: SchemaConfigurator {
+
+  override fun serializableMemberProperties(clazz: KClass<*>): Collection<KProperty1<out Any, *>> =
+    clazz.memberProperties
+      .filterNot {
+        it.hasJavaAnnotation<JsonIgnore>()
+      }
+
+  override fun serializableName(property: KProperty1<out Any, *>): String =
+    property.getJavaAnnotation<JsonProperty>()?.value?: property.name
+
+}
+
+inline fun <reified T: Annotation> KProperty1<*, *>.hasJavaAnnotation(): Boolean {
+  return javaField?.isAnnotationPresent(T::class.java)?: false
+}
+
+inline fun <reified T: Annotation> KProperty1<*, *>.getJavaAnnotation(): T? {
+  return javaField?.getDeclaredAnnotation(T::class.java)
+}
--- a/core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/TestHelpers.kt
+++ b/core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/TestHelpers.kt
@ -5,13 +5,10 @@ import com.fasterxml.jackson.databind.SerializationFeature
 import io.bkbn.kompendium.core.fixtures.TestSpecs.defaultSpec
 import io.bkbn.kompendium.core.plugin.NotarizedApplication
 import io.bkbn.kompendium.core.routes.redoc
+import io.bkbn.kompendium.json.schema.KotlinXSchemaConfigurator
 import io.bkbn.kompendium.json.schema.definition.JsonSchema
 import io.bkbn.kompendium.oas.OpenApiSpec
-import io.bkbn.kompendium.oas.info.Contact
-import io.bkbn.kompendium.oas.info.Info
-import io.bkbn.kompendium.oas.info.License
 import io.bkbn.kompendium.oas.serialization.KompendiumSerializersModule
-import io.bkbn.kompendium.oas.server.Server
 import io.kotest.assertions.json.shouldEqualJson
 import io.kotest.assertions.ktor.client.shouldHaveStatus
 import io.kotest.matchers.shouldNot
@ -31,7 +28,6 @@ import io.ktor.server.testing.testApplication
 import kotlin.reflect.KType
 import kotlinx.serialization.json.Json
 import java.io.File
-import java.net.URI

 object TestHelpers {
  private const val OPEN_API_ENDPOINT = "/openapi.json"
@ -83,6 +79,11 @@ object TestHelpers {
    install(NotarizedApplication()) {
      customTypes = typeOverrides
      spec = defaultSpec().specOverrides()
+      schemaConfigurator = when (serializer) {
+        SupportedSerializer.KOTLINX -> KotlinXSchemaConfigurator()
+        SupportedSerializer.GSON -> GsonSchemaConfigurator()
+        SupportedSerializer.JACKSON -> JacksonSchemaConfigurator()
+      }
    }
    install(ContentNegotiation) {
      when (serializer) {
--- a/core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/TestModels.kt
+++ b/core/src/testFixtures/kotlin/io/bkbn/kompendium/core/fixtures/TestModels.kt
@ -1,6 +1,12 @@
 package io.bkbn.kompendium.core.fixtures

+import com.fasterxml.jackson.annotation.JsonIgnore
+import com.fasterxml.jackson.annotation.JsonProperty
+import com.google.gson.annotations.Expose
+import com.google.gson.annotations.SerializedName
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.Transient
 import java.time.Instant

@Serializable
@ -146,3 +152,27 @@ object Nested {
  @Serializable
  data class Response(val idk: Boolean)
 }
+
+@Serializable
+data class TransientObject(
+  @field:Expose
+  val nonTransient: String,
+  @field:JsonIgnore
+  @Transient
+  val transient: String = "transient"
+)
+
+@Serializable
+data class UnbakcedObject(
+  val backed: String
+) {
+  val unbacked: String get() = "unbacked"
+}
+
+@Serializable
+data class SerialNameObject(
+  @field:JsonProperty("snake_case_name")
+  @field:SerializedName("snake_case_name")
+  @SerialName("snake_case_name")
+  val camelCaseName: String
+)