Merge branch 'develop' into release

Author: SMILEY4

gradle.properties

@@ -3,7 +3,7 @@ kotlin.code.style=official
 # project id
 projectGroupId=io.github.smiley4
 projectArtifactIdBase=ktor-swagger-ui
-projectVersion=3.2.0
+projectVersion=3.3.0
 
 # publishing information
 projectNameBase=Ktor Swagger UI
@@ -19,7 +19,7 @@ projectDeveloperUrl=https://github.com/SMILEY4
 versionKtor=2.3.11
 versionSwaggerUI=5.17.11
 versionSwaggerParser=2.1.22
-versionSchemaKenerator=1.0.1
+versionSchemaKenerator=1.1.0
 versionKotlinLogging=3.0.5
 versionKotest=5.8.0
 versionKotlinTest=1.8.21

ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/CompleteConfig.kt

@@ -138,7 +138,7 @@ private fun Application.myModule() {
         specAssigner = { _, _ -> PluginConfigDsl.DEFAULT_SPEC_ID }
         pathFilter = { _, url -> url.firstOrNull() != "hidden" }
         ignoredRouteSelectors = emptySet()
-        postBuild = { api -> println("Completed api: $api") }
+        postBuild = { api, name -> println("Completed api '$name': $api") }
     }
 
 

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/SwaggerPlugin.kt

@@ -30,7 +30,6 @@ 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
@@ -83,12 +82,12 @@ private fun buildOpenApiSpecs(config: PluginConfigData, routes: List<RouteMeta>)
     return buildMap {
         routesBySpec.forEach { (specName, routes) ->
             val specConfig = config.specConfigs[specName] ?: config
-            this[specName] = buildOpenApiSpec(specConfig, routes)
+            this[specName] = buildOpenApiSpec(specName, specConfig, routes)
         }
     }
 }
 
-private fun buildOpenApiSpec(pluginConfig: PluginConfigData, routes: List<RouteMeta>): String {
+private fun buildOpenApiSpec(specName: String, pluginConfig: PluginConfigData, routes: List<RouteMeta>): String {
     return try {
         val schemaContext = SchemaContextImpl(pluginConfig.schemaConfig).also {
             it.addGlobal(pluginConfig.schemaConfig)
@@ -99,7 +98,7 @@ private fun buildOpenApiSpec(pluginConfig: PluginConfigData, routes: List<RouteM
             it.add(routes)
         }
         val openApi = builder(pluginConfig, schemaContext, exampleContext).build(routes)
-        pluginConfig.postBuild?.invoke(openApi)
+        pluginConfig.postBuild?.let { it(openApi, specName) }
         Json.pretty(openApi)
     } catch (e: Exception) {
         logger.error("Error during openapi-generation", e)

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/DataUtils.kt

@@ -2,10 +2,23 @@ package io.github.smiley4.ktorswaggerui.data
 
 object DataUtils {
 
+    /**
+     * Merges the two boolean values.
+     * @return true if "value" is true, value of "base" otherwise
+     */
     fun mergeBoolean(base: Boolean, value: Boolean) = if (value) true else base
 
+
+    /**
+     * Merges the two values.
+     * @return "value" if "value" is different from the given default value, "base" otherwise
+     */
     fun <T> mergeDefault(base: T, value: T, default: T) = if (value != default) value else base
 
+    /**
+     * Merges the two values.
+     * @return "value" if "value" is not null, "base" otherwise
+     */
     fun <T> merge(base: T?, value: T?) = value ?: base
 
 }

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/PostBuild.kt

@@ -6,4 +6,4 @@ import io.swagger.v3.oas.models.OpenAPI
  * Function executed after building the openapi-spec.
  * @author <a href=mailto:mcxinyu@foxmail.com>yuefeng</a> in 2024/3/25.
  */
-typealias PostBuild = (openApi: OpenAPI) -> Unit
+typealias PostBuild = (openApi: OpenAPI, specId: String) -> Unit

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt

@@ -55,6 +55,10 @@ class ExampleConfig {
         this.exampleEncoder = exampleEncoder
     }
 
+    /**
+     * Build the data object for this config.
+     * @param securityConfig the data for security config that might contain additional examples
+     */
     fun build(securityConfig: SecurityData) = ExampleConfigData(
         sharedExamples = sharedExamples,
         securityExamples = securityConfig.defaultUnauthorizedResponse?.body?.let {

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiContact.kt

@@ -28,6 +28,10 @@ class OpenApiContact {
     var email: String? = ContactData.DEFAULT.email
 
 
+    /**
+     * Build the data object for this config.
+     * @param base the base config to "inherit" from. Values from the base should be copied, replaced or merged together.
+     */
     fun build(base: ContactData) = ContactData(
         name = merge(base.name, name),
         url = merge(base.url, url),

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiExternalDocs.kt

@@ -21,7 +21,10 @@ class OpenApiExternalDocs {
      */
     var url: String = "/"
 
-
+    /**
+     * Build the data object for this config.
+     * @param base the base config to "inherit" from. Values from the base should be copied, replaced or merged together.
+     */
     fun build(base: ExternalDocsData) = ExternalDocsData(
         url = DataUtils.mergeDefault(base.url, url, ExternalDocsData.DEFAULT.url),
         description = DataUtils.merge(base.description, description)

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiInfo.kt

@@ -62,7 +62,10 @@ class OpenApiInfo {
         license = OpenApiLicense().apply(block)
     }
 
-
+    /**
+     * Build the data object for this config.
+     * @param base the base config to "inherit" from. Values from the base should be copied, replaced or merged together.
+     */
     fun build(base: InfoData): InfoData {
         return InfoData(
             title = mergeDefault(base.title, this.title, InfoData.DEFAULT.title),

ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiLicense.kt

@@ -27,6 +27,10 @@ class OpenApiLicense {
      */
     var identifier: String? = LicenseData.DEFAULT.identifier
 
+    /**
+     * Build the data object for this config.
+     * @param base the base config to "inherit" from. Values from the base should be copied, replaced or merged together.
+     */
     fun build(base: LicenseData) = LicenseData(
         name = DataUtils.merge(base.name, name),
         url = DataUtils.merge(base.url, url),