add example encoder config option

SMILEY4 · Jun 27, 2024 · aec52a8 · aec52a8
1 parent 058fbbf
commit aec52a8
Show file tree

Hide file tree

Showing 11 changed files with 73 additions and 23 deletions.
diff --git a/...-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Examples.kt b/...-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Examples.kt
@@ -1,6 +1,7 @@
 package io.github.smiley4.ktorswaggerui.examples
 
 import io.github.smiley4.ktorswaggerui.SwaggerUI
+import io.github.smiley4.ktorswaggerui.data.KTypeDescriptor
 import io.github.smiley4.ktorswaggerui.dsl.routing.get
 import io.github.smiley4.ktorswaggerui.routing.openApiSpec
 import io.github.smiley4.ktorswaggerui.routing.swaggerUI
@@ -12,6 +13,7 @@ import io.ktor.server.netty.Netty
 import io.ktor.server.response.respondText
 import io.ktor.server.routing.route
 import io.ktor.server.routing.routing
+import kotlin.reflect.typeOf
 
 fun main() {
     embeddedServer(Netty, port = 8080, host = "localhost", module = Application::myModule).start(wait = true)
@@ -37,6 +39,15 @@ private fun Application.myModule() {
                 )
             }
 
+            // encoder used in "custom-encoder" example
+            encoder { type, example ->
+                // encode just the wrapped value for CustomEncoderData class
+                if (type is KTypeDescriptor && type.type == typeOf<CustomEncoderData>())
+                    (example as CustomEncoderData).number
+                // return the example unmodified to fall back to default encoder
+                else
+                    example
+            }
         }
     }
 
@@ -86,6 +97,19 @@ private fun Application.myModule() {
             call.respondText("...")
         }
 
+        get("custom-encoder", {
+            request {
+                body<CustomEncoderData> {
+                    // The type is CustomEncoderData, but it's actually encoded as a plain number
+                    // See configuration for encoder
+                    example("Example 1") {
+                        value = CustomEncoderData(123)
+                    }
+                }
+            }
+        }) {
+            call.respondText("...")
+        }
     }
 
 }
@@ -94,3 +118,7 @@ private fun Application.myModule() {
 private data class MyExampleClass(
     val someValue: String
 )
+
+private data class CustomEncoderData(
+    val number: Int
+)
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/SwaggerPlugin.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/SwaggerPlugin.kt
@@ -30,6 +30,7 @@ import io.github.smiley4.ktorswaggerui.builder.route.RouteMeta
 import io.github.smiley4.ktorswaggerui.builder.schema.SchemaContext
 import io.github.smiley4.ktorswaggerui.builder.schema.SchemaContextImpl
 import io.github.smiley4.ktorswaggerui.data.PluginConfigData
+import io.github.smiley4.ktorswaggerui.data.TypeDescriptor
 import io.github.smiley4.ktorswaggerui.dsl.config.PluginConfigDsl
 import io.github.smiley4.ktorswaggerui.routing.ApiSpec
 import io.ktor.server.application.Application
@@ -93,7 +94,7 @@ private fun buildOpenApiSpec(pluginConfig: PluginConfigData, routes: List<RouteM
             it.addGlobal(pluginConfig.schemaConfig)
             it.add(routes)
         }
-        val exampleContext = ExampleContextImpl().also {
+        val exampleContext = ExampleContextImpl(pluginConfig.exampleConfig.exampleEncoder).also {
             it.addShared(pluginConfig.exampleConfig)
             it.add(routes)
         }

diff --git a/...gger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContext.kt b/...gger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContext.kt
@@ -1,6 +1,7 @@
 package io.github.smiley4.ktorswaggerui.builder.example
 
 import io.github.smiley4.ktorswaggerui.data.ExampleDescriptor
+import io.github.smiley4.ktorswaggerui.data.TypeDescriptor
 import io.swagger.v3.oas.models.examples.Example
 
 /**
@@ -9,9 +10,10 @@ import io.swagger.v3.oas.models.examples.Example
 interface ExampleContext {
 
     /**
-     * Get an [Example] (or a ref to an example) by its [ExampleDescriptor]
+     * Get an [Example] (or a ref to an example) by its [ExampleDescriptor],
+     * and its type, which may be used to encode the example first.
      */
-    fun getExample(descriptor: ExampleDescriptor): Example
+    fun getExample(descriptor: ExampleDescriptor, type: TypeDescriptor): Example
 
 
     /**

diff --git a/...-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContextImpl.kt b/...-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContextImpl.kt
@@ -7,9 +7,9 @@ import io.swagger.v3.oas.models.examples.Example
 /**
  * Implementation of an [ExampleContext].
  */
-class ExampleContextImpl : ExampleContext {
+class ExampleContextImpl(private val encoder: ExampleEncoder?) : ExampleContext {
 
-    private val rootExamples = mutableMapOf<ExampleDescriptor, Example>()
+    private val rootExamples = mutableMapOf<ExampleDescriptor, ExampleDescriptor>()
     private val componentExamples = mutableMapOf<String, Example>()
 
 
@@ -18,12 +18,11 @@ class ExampleContextImpl : ExampleContext {
      */
     fun addShared(config: ExampleConfigData) {
         config.sharedExamples.forEach { (_, exampleDescriptor) ->
-            val example = generateExample(exampleDescriptor)
+            val example = generateExample(exampleDescriptor, null)
             componentExamples[exampleDescriptor.name] = example
         }
         config.securityExamples.forEach { exampleDescriptor ->
-            val example = generateExample(exampleDescriptor)
-            rootExamples[exampleDescriptor] = example
+            rootExamples[exampleDescriptor] = exampleDescriptor
         }
     }
 
@@ -33,7 +32,7 @@ class ExampleContextImpl : ExampleContext {
      */
     fun add(routes: Collection<RouteMeta>) {
         collectExampleDescriptors(routes).forEach { exampleDescriptor ->
-            rootExamples[exampleDescriptor] = generateExample(exampleDescriptor)
+            rootExamples[exampleDescriptor] = exampleDescriptor
         }
     }
 
@@ -71,22 +70,29 @@ class ExampleContextImpl : ExampleContext {
     /**
      * Generate a swagger [Example] from the given [ExampleDescriptor]
      */
-    private fun generateExample(exampleDescriptor: ExampleDescriptor): Example {
+    private fun generateExample(exampleDescriptor: ExampleDescriptor, type: TypeDescriptor?): Example {
         return when (exampleDescriptor) {
             is ValueExampleDescriptor -> Example().also {
-                it.value = exampleDescriptor.value
+                it.value =
+                    if (encoder != null) encoder.invoke(type, exampleDescriptor.value)
+                    else exampleDescriptor.value
                 it.summary = exampleDescriptor.summary
                 it.description = exampleDescriptor.description
             }
+
             is RefExampleDescriptor -> Example().also {
                 it.`$ref` = "#/components/examples/${exampleDescriptor.refName}"
             }
+
             is SwaggerExampleDescriptor -> exampleDescriptor.example
         }
     }
 
-    override fun getExample(descriptor: ExampleDescriptor): Example {
-        return rootExamples[descriptor] ?: throw NoSuchElementException("no root-example for given example-descriptor")
+    override fun getExample(descriptor: ExampleDescriptor, type: TypeDescriptor): Example {
+        return generateExample(
+            rootExamples[descriptor] ?: throw NoSuchElementException("no root-example for given example-descriptor"),
+            type
+        )
     }
 
     override fun getComponentSection(): Map<String, Example> {

diff --git a/...gger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/openapi/ContentBuilder.kt b/...gger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/openapi/ContentBuilder.kt
@@ -53,7 +53,7 @@ class ContentBuilder(
         return MediaType().also {
             it.schema = schema
             body.examples.forEach { descriptor ->
-                it.addExamples(descriptor.name, exampleContext.getExample(descriptor))
+                it.addExamples(descriptor.name, exampleContext.getExample(descriptor, body.type))
             }
         }
     }

diff --git a/...er-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/openapi/ParameterBuilder.kt b/...er-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/openapi/ParameterBuilder.kt
@@ -28,7 +28,7 @@ class ParameterBuilder(
             it.deprecated = parameter.deprecated
             it.allowEmptyValue = parameter.allowEmptyValue
             it.explode = parameter.explode
-            it.example = parameter.example?.let { e -> exampleContext.getExample(e).value } // todo: example"S" ?
+            it.example = parameter.example?.let { e -> exampleContext.getExample(e, parameter.type).value } // todo: example"S" ?
             it.allowReserved = parameter.allowReserved
             it.schema = schemaContext.getSchema(parameter.type)
             it.style = parameter.style

diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/ExampleConfigData.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/ExampleConfigData.kt
@@ -1,14 +1,22 @@
 package io.github.smiley4.ktorswaggerui.data
 
+/**
+ * Encoder to produce the final example value.
+ * Return the unmodified example to fall back to the default encoder.
+ */
+typealias ExampleEncoder = (type: TypeDescriptor?, example: Any?) -> Any?
+
 class ExampleConfigData(
     val sharedExamples: Map<String, ExampleDescriptor>,
-    val securityExamples: List<ExampleDescriptor>
+    val securityExamples: List<ExampleDescriptor>,
+    val exampleEncoder: ExampleEncoder?
 ) {
 
     companion object {
         val DEFAULT = ExampleConfigData(
             sharedExamples = emptyMap(),
-            securityExamples = emptyList()
+            securityExamples = emptyList(),
+            exampleEncoder = null
         )
     }
 

diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt
@@ -6,12 +6,13 @@ import io.github.smiley4.ktorswaggerui.dsl.routes.ValueExampleDescriptorDsl
 import io.swagger.v3.oas.models.examples.Example
 
 /**
- * Configuration for schemas
+ * Configuration for examples
  */
 @OpenApiDslMarker
 class ExampleConfig {
 
     val sharedExamples = mutableMapOf<String, ExampleDescriptor>()
+    var exampleEncoder: ExampleEncoder? = null
 
     fun example(example: ExampleDescriptor) {
         sharedExamples[example.name] = example
@@ -32,14 +33,18 @@ class ExampleConfig {
             }
     )
 
+    fun encoder(exampleEncoder: ExampleEncoder) {
+        this.exampleEncoder = exampleEncoder
+    }
+
     fun build(securityConfig: SecurityData) = ExampleConfigData(
         sharedExamples = sharedExamples,
         securityExamples = securityConfig.defaultUnauthorizedResponse?.body?.let {
             when (it) {
                 is OpenApiSimpleBodyData -> it.examples
                 is OpenApiMultipartBodyData -> emptyList()
             }
-        } ?: emptyList()
+        } ?: emptyList(),
+        exampleEncoder = exampleEncoder
     )
-
 }
diff --git a/...-swagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OpenApiBuilderTest.kt b/...-swagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OpenApiBuilderTest.kt
@@ -116,7 +116,7 @@ class OpenApiBuilderTest : StringSpec({
 
         private fun exampleContext(routes: List<RouteMeta>, pluginConfig: PluginConfigDsl): ExampleContext {
             val pluginConfigData = pluginConfig.build(PluginConfigData.DEFAULT)
-            return ExampleContextImpl().also {
+            return ExampleContextImpl(pluginConfigData.exampleConfig.exampleEncoder).also {
                 it.addShared(pluginConfigData.exampleConfig)
                 it.add(routes)
             }

diff --git a/...wagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OperationBuilderTest.kt b/...wagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OperationBuilderTest.kt
@@ -998,7 +998,7 @@ class OperationBuilderTest : StringSpec({
 
         private fun exampleContext(routes: List<RouteMeta>, pluginConfig: PluginConfigDsl = defaultPluginConfig): ExampleContext {
             val pluginConfigData = pluginConfig.build(PluginConfigData.DEFAULT)
-            return ExampleContextImpl().also {
+            return ExampleContextImpl(pluginConfigData.exampleConfig.exampleEncoder).also {
                 it.addShared(pluginConfigData.exampleConfig)
                 it.add(routes)
             }

diff --git a/ktor-swagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/PathsBuilderTest.kt b/ktor-swagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/PathsBuilderTest.kt
@@ -95,7 +95,7 @@ class PathsBuilderTest : StringSpec({
 
         private fun exampleContext(routes: List<RouteMeta>, pluginConfig: PluginConfigDsl): ExampleContext {
             val pluginConfigData = pluginConfig.build(PluginConfigData.DEFAULT)
-            return ExampleContextImpl().also {
+            return ExampleContextImpl(pluginConfigData.exampleConfig.exampleEncoder).also {
                 it.addShared(pluginConfigData.exampleConfig)
                 it.add(routes)
             }