Merge branch 'develop' into release

Author: SMILEY4

docs/changelog.md

@@ -5,6 +5,12 @@ search:
 
 # Changelog
 
+## 5.5.0
+
+- added Jackson example encoder configured for use with Kotlin (now the new default)
+- upgrade schema-kenerator from 2.5.0 to [2.6.0](https://github.com/SMILEY4/schema-kenerator/releases/tag/2.6.0)
+- fix: kotlinx-serialization example encoding  [#226](https://github.com/SMILEY4/ktor-openapi-tools/pull/226)
+
 ## 5.4.0
 
 - support for ReDoc extensions `x-displayName` and `x-tagGroups` [#221](https://github.com/SMILEY4/ktor-openapi-tools/pull/221), [#219](https://github.com/SMILEY4/ktor-openapi-tools/pull/219)

docs/openapi/providing_openapi_specification.md

@@ -50,7 +50,7 @@ val format: OutputFormat = OpenApiPlugin.getOpenApiSpecFormat( // (2)!
 Specifications can be regenerated programmatically at any time.
 
 ```kotlin
-OpenApiPlugin.regenerateOpenApiSpec(OpenApiPluginConfig.DEFAULT_SPEC_ID) 
+OpenApiPlugin.generateOpenApiSpecs(OpenApiPluginConfig.DEFAULT_SPEC_ID) 
 ```
 
 This discards a previously created specification, collects all routes and information again and generates a new specification.

gradle.properties

@@ -2,7 +2,7 @@ kotlin.code.style=official
 
 # project id
 projectGroupId=io.github.smiley4
-projectVersion=5.4.0
+projectVersion=5.5.0
 
 # common publishing information
 projectBaseScmUrl=https://github.com/SMILEY4/
@@ -16,7 +16,7 @@ projectDeveloperUrl=https://github.com/SMILEY4
 versionKtor=3.3.2
 versionSwaggerUI=5.17.14
 versionSwaggerParser=2.1.24
-versionSchemaKenerator=2.5.0
+versionSchemaKenerator=2.6.0
 versionKotlinLogging=7.0.0
 versionKotest=5.8.0
 versionKotlinTest=2.0.21

ktor-openapi/build.gradle.kts

@@ -60,6 +60,9 @@ dependencies {
     val versionMockk: String by project
     testImplementation("io.mockk:mockk:$versionMockk")
 
+    val versionLogback: String by project
+    testImplementation("ch.qos.logback:logback-classic:$versionLogback")
+
 }
 
 kotlin {

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/config/ExampleEncoder.kt

@@ -1,6 +1,6 @@
 package io.github.smiley4.ktoropenapi.config
 
-import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import io.github.smiley4.ktoropenapi.config.descriptors.KTypeDescriptor
 import io.github.smiley4.ktoropenapi.config.descriptors.TypeDescriptor
@@ -23,17 +23,25 @@ object ExampleEncoder {
         example
     }
 
+    /**
+     * [GenericExampleEncoder] using a Jackson mapper to encode example objects.
+     * @param json a jackson object mapper encoding objects to json. Set `null` to use a pre-configured object mapper.
+     */
+    fun jackson(json: ObjectMapper? = null): GenericExampleEncoder = { type, example ->
+        val mapper = json ?: jacksonObjectMapper()
+        mapper.writeValueAsString(example)
+    }
+
     /**
      * [GenericExampleEncoder] using kotlinx-serialization to encode example objects.
-     * @param json the kotlinx json serializer to use for encoding objects to json. Set `null` to use default kotlinx json serializer.
+     * @param json a kotlinx json serializer to use for encoding objects to json. Set `null` to use default kotlinx json serializer.
      */
     fun kotlinx(json: Json? = null): GenericExampleEncoder = { type, example ->
         when(type) {
             is KTypeDescriptor -> {
                 val jsonEncoder = json ?: Json
-                val jsonString = jsonEncoder.encodeToString(serializer(type.type), example)
-                val jsonObj = jacksonObjectMapper().readValue(jsonString, object : TypeReference<Any>() {})
-                jsonObj
+                val serializer = jsonEncoder.serializersModule.serializer(type.type)
+                jsonEncoder.encodeToString(serializer, example)
             }
             else -> example
         }

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/data/ExampleConfigData.kt

@@ -14,7 +14,7 @@ internal class ExampleConfigData(
         val DEFAULT = ExampleConfigData(
             sharedExamples = emptyMap(),
             securityExamples = null,
-            exampleEncoder = ExampleEncoder.internal()
+            exampleEncoder = ExampleEncoder.jackson()
         )
     }
 

ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/builder/OperationBuilderTest.kt

@@ -440,7 +440,7 @@ class OperationBuilderTest : StringSpec({
                     param.schema
                         .also { it.shouldNotBeNull() }
                         ?.also { it.type = "string" }
-                    param.example shouldBe "MyExample"
+                    param.example shouldBe "\"MyExample\""
                     param.examples shouldBe null
                     param.content shouldBe null
                     param.extensions shouldBe null
@@ -501,7 +501,7 @@ class OperationBuilderTest : StringSpec({
                                         ?.also { example ->
                                             example.summary shouldBe "the example 1"
                                             example.description shouldBe "the first example"
-                                            example.value shouldBe "MyExample1"
+                                            example.value shouldBe "\"MyExample1\""
                                             example.externalValue shouldBe null
                                             example.`$ref` shouldBe null
                                             example.extensions shouldBe null
@@ -525,7 +525,7 @@ class OperationBuilderTest : StringSpec({
                                         ?.also { example ->
                                             example.summary shouldBe "the example 1"
                                             example.description shouldBe "the first example"
-                                            example.value shouldBe "MyExample1"
+                                            example.value shouldBe "\"MyExample1\""
                                             example.externalValue shouldBe null
                                             example.`$ref` shouldBe null
                                             example.extensions shouldBe null
@@ -787,7 +787,7 @@ class OperationBuilderTest : StringSpec({
                             content.schema.`$ref` shouldBe "#/components/schemas/${SimpleObject::class.qualifiedName}"
                             val example = content.examples["Example 1"]
                             example.shouldNotBeNull()
-                            example.value shouldBeEqual SimpleObject(text = "Some text", number = 123)
+                            example.value shouldBeEqual "{\"text\":\"Some text\",\"number\":123}"
                         }
                     responses["default"]
                         .also { it.shouldNotBeNull() }

ktor-openapi/src/test/kotlin/io/github/smiley4/ktorswaggerui/misc/ExampleEncoderTest.kt

@@ -0,0 +1,71 @@
+package io.github.smiley4.ktorswaggerui.misc
+
+import io.github.smiley4.ktoropenapi.OpenApi
+import io.github.smiley4.ktoropenapi.config.ExampleEncoder
+import io.github.smiley4.ktoropenapi.get
+import io.github.smiley4.ktoropenapi.openApi
+import io.kotest.core.spec.style.StringSpec
+import io.kotest.matchers.shouldNotBe
+import io.ktor.client.request.get
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.HttpStatusCode
+import io.ktor.server.response.respond
+import io.ktor.server.routing.route
+import io.ktor.server.testing.testApplication
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.descriptors.PrimitiveKind
+import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.modules.SerializersModule
+import java.time.LocalDate
+import java.time.format.DateTimeFormatter
+
+
+class ExampleEncoderTest : StringSpec({
+
+    val json = Json {
+        classDiscriminator = "_type"
+        serializersModule = SerializersModule {
+            contextual(LocalDate::class, object : KSerializer<LocalDate> {
+                private val formatter: DateTimeFormatter = DateTimeFormatter.ISO_LOCAL_DATE
+                override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("LocalDate", PrimitiveKind.STRING)
+                override fun deserialize(decoder: Decoder) = LocalDate.parse(decoder.decodeString(), formatter)
+                override fun serialize(encoder: Encoder, value: LocalDate) = encoder.encodeString(formatter.format(value))
+            })
+        }
+    }
+
+    "ExampleEncoder.kotlinx should not fail with contextual type" {
+        testApplication {
+            install(OpenApi) {
+                examples {
+                    encoder(ExampleEncoder.kotlinx(json))
+                }
+            }
+            routing {
+                route("api.yml") {
+                    openApi()
+                }
+
+                get("test", {
+                    response {
+                        HttpStatusCode.OK to {
+                            body<LocalDate> {
+                                example("example") {
+                                    value = LocalDate.of(2025, 12, 9)
+                                }
+                            }
+                        }
+                    }
+                }) {
+                    call.respond(HttpStatusCode.OK)
+                }
+            }
+
+            createClient {}.get("api.yml").bodyAsText() shouldNotBe "{}"
+        }
+    }
+})