Merge branch 'develop' into release

.github/workflows/checks.yml

@@ -1,6 +1,6 @@
 name: Checks
 
-on: [ push, pull_request ]
+on: [ push, pull_request, workflow_dispatch ]
 
 permissions:
     contents: read

gradle.properties

@@ -3,7 +3,7 @@ kotlin.code.style=official
 # project id
 projectGroupId=io.github.smiley4
 projectArtifactIdBase=ktor-swagger-ui
-projectVersion=3.0.1
+projectVersion=3.1.0
 
 # publishing information
 projectNameBase=Ktor Swagger UI

ktor-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
+)

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)
         }

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContext.kt

@@ -9,7 +9,7 @@ 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].
      */
     fun getExample(descriptor: ExampleDescriptor): Example
 

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContextImpl.kt

@@ -7,7 +7,7 @@ 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 componentExamples = mutableMapOf<String, Example>()
@@ -18,11 +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)
+            val example = generateExample(exampleDescriptor, null)
             rootExamples[exampleDescriptor] = example
         }
     }
@@ -32,55 +32,59 @@ class ExampleContextImpl : ExampleContext {
      * Collect and add all examples for the given routes
      */
     fun add(routes: Collection<RouteMeta>) {
-        collectExampleDescriptors(routes).forEach { exampleDescriptor ->
-            rootExamples[exampleDescriptor] = generateExample(exampleDescriptor)
+        collectExampleDescriptors(routes).forEach { (exampleDescriptor, typeDescriptor) ->
+            val example = generateExample(exampleDescriptor, typeDescriptor)
+            rootExamples[exampleDescriptor] = example
         }
     }
 
 
     /**
      * Collect all [ExampleDescriptor]s from the given routes
      */
-    private fun collectExampleDescriptors(routes: Collection<RouteMeta>): List<ExampleDescriptor> {
-        val descriptors = mutableListOf<ExampleDescriptor>()
-        routes
-            .filter { !it.documentation.hidden }
-            .forEach { route ->
-                route.documentation.request.also { request ->
-                    request.parameters.forEach { parameter ->
-                        parameter.example?.also { descriptors.add(it) }
-                    }
-                    request.body?.also { body ->
-                        if (body is OpenApiSimpleBodyData) {
-                            descriptors.addAll(body.examples)
+    private fun collectExampleDescriptors(routes: Collection<RouteMeta>): List<Pair<ExampleDescriptor, TypeDescriptor>> =
+        buildList {
+            routes
+                .filter { !it.documentation.hidden }
+                .forEach { route ->
+                    route.documentation.request.also { request ->
+                        request.parameters.forEach { parameter ->
+                            parameter.example?.also { add(it to parameter.type) }
+                        }
+                        request.body?.also { body ->
+                            if (body is OpenApiSimpleBodyData) {
+                                addAll(body.examples.map { it to body.type })
+                            }
                         }
                     }
-                }
-                route.documentation.responses.forEach { response ->
-                    response.body?.also { body ->
-                        if (body is OpenApiSimpleBodyData) {
-                            descriptors.addAll(body.examples)
+                    route.documentation.responses.forEach { response ->
+                        response.body?.also { body ->
+                            if (body is OpenApiSimpleBodyData) {
+                                addAll(body.examples.map { it to body.type })
+                            }
                         }
                     }
                 }
-            }
-        return descriptors
-    }
+        }
 
 
     /**
      * 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
         }
     }

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/openapi/ContentBuilder.kt

@@ -5,7 +5,7 @@ import io.github.smiley4.ktorswaggerui.builder.schema.SchemaContext
 import io.github.smiley4.ktorswaggerui.data.OpenApiBaseBodyData
 import io.github.smiley4.ktorswaggerui.data.OpenApiMultipartBodyData
 import io.github.smiley4.ktorswaggerui.data.OpenApiSimpleBodyData
-import io.ktor.http.ContentType
+import io.ktor.http.*
 import io.swagger.v3.oas.models.media.Content
 import io.swagger.v3.oas.models.media.Encoding
 import io.swagger.v3.oas.models.media.MediaType

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
         )
     }
 

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
     )
-
 }

ktor-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)
             }

ktor-swagger-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)
             }

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)
             }