Merge branch 'support-spec-as-yaml' into develop

SMILEY4 · Oct 20, 2024 · 09ed474 · 09ed474
2 parents 2d1a1f7 + accc878
commit 09ed474
Show file tree

Hide file tree

Showing 8 changed files with 96 additions and 88 deletions.
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Test.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Test.kt
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
@@ -43,6 +43,8 @@ import io.ktor.server.routing.Routing
 import io.ktor.server.webjars.Webjars
 import io.swagger.v3.core.util.Json31
 import io.github.oshai.kotlinlogging.KotlinLogging
+import io.github.smiley4.ktorswaggerui.data.OutputFormat
+import io.swagger.v3.core.util.Yaml31
 
 /**
  * This version must match the version of the gradle dependency
@@ -72,7 +74,7 @@ val SwaggerUI = createApplicationPlugin(name = "SwaggerUI", createConfiguration
     }
 }
 
-private fun buildOpenApiSpecs(config: PluginConfigData, routes: List<RouteMeta>): Map<String, String> {
+private fun buildOpenApiSpecs(config: PluginConfigData, routes: List<RouteMeta>): Map<String, Pair<String, OutputFormat>> {
     val routesBySpec = buildMap<String, MutableList<RouteMeta>> {
         routes.forEach { route ->
             val specName =
@@ -88,7 +90,7 @@ private fun buildOpenApiSpecs(config: PluginConfigData, routes: List<RouteMeta>)
     }
 }
 
-private fun buildOpenApiSpec(specName: String, pluginConfig: PluginConfigData, routes: List<RouteMeta>): String {
+private fun buildOpenApiSpec(specName: String, pluginConfig: PluginConfigData, routes: List<RouteMeta>): Pair<String, OutputFormat> {
     return try {
         val schemaContext = SchemaContextImpl(pluginConfig.schemaConfig).also {
             it.addGlobal(pluginConfig.schemaConfig)
@@ -100,10 +102,13 @@ private fun buildOpenApiSpec(specName: String, pluginConfig: PluginConfigData, r
         }
         val openApi = builder(pluginConfig, schemaContext, exampleContext).build(routes)
         pluginConfig.postBuild?.let { it(openApi, specName) }
-        Json31.pretty(openApi)
+        when(pluginConfig.outputFormat) {
+            OutputFormat.JSON -> Json31.pretty(openApi) to pluginConfig.outputFormat
+            OutputFormat.YAML -> Yaml31.pretty(openApi) to pluginConfig.outputFormat
+        }
     } catch (e: Exception) {
         logger.error(e) { "Error during openapi-generation" }
-        "{}"
+        return pluginConfig.outputFormat.empty to pluginConfig.outputFormat
     }
 }
 

diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/OutputFormat.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/OutputFormat.kt
@@ -0,0 +1,6 @@
+package io.github.smiley4.ktorswaggerui.data
+
+enum class OutputFormat(val empty: String) {
+    JSON("{}"),
+    YAML("")
+}
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/PluginConfigData.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/PluginConfigData.kt
@@ -19,7 +19,8 @@ data class PluginConfigData(
     val schemaConfig: SchemaConfigData,
     val exampleConfig: ExampleConfigData,
     val securityConfig: SecurityData,
-    val tagsConfig: TagsData
+    val tagsConfig: TagsData,
+    val outputFormat: OutputFormat
 ) {
 
     companion object {
@@ -36,7 +37,8 @@ data class PluginConfigData(
             schemaConfig = SchemaConfigData.DEFAULT,
             exampleConfig = ExampleConfigData.DEFAULT,
             securityConfig = SecurityData.DEFAULT,
-            tagsConfig = TagsData.DEFAULT
+            tagsConfig = TagsData.DEFAULT,
+            outputFormat = OutputFormat.JSON
         )
     }
 

diff --git a/...-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/PluginConfigDsl.kt b/...-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/PluginConfigDsl.kt
@@ -1,9 +1,14 @@
 package io.github.smiley4.ktorswaggerui.dsl.config
 
-import io.github.smiley4.ktorswaggerui.data.*
 import io.github.smiley4.ktorswaggerui.data.DataUtils.merge
+import io.github.smiley4.ktorswaggerui.data.OutputFormat
+import io.github.smiley4.ktorswaggerui.data.PathFilter
+import io.github.smiley4.ktorswaggerui.data.PluginConfigData
+import io.github.smiley4.ktorswaggerui.data.PostBuild
+import io.github.smiley4.ktorswaggerui.data.ServerData
+import io.github.smiley4.ktorswaggerui.data.SpecAssigner
 import io.github.smiley4.ktorswaggerui.dsl.OpenApiDslMarker
-import io.ktor.server.routing.*
+import io.ktor.server.routing.RouteSelector
 import kotlin.collections.component1
 import kotlin.collections.component2
 import kotlin.collections.set
@@ -109,6 +114,7 @@ class PluginConfigDsl {
 
     private val specConfigs = mutableMapOf<String, PluginConfigDsl>()
 
+
     /**
      * Assigns routes without an [io.github.smiley4.ktorswaggerui.dsl.routes.OpenApiRoute.specId]] to a specified openapi-spec.
      */
@@ -128,6 +134,12 @@ class PluginConfigDsl {
     var ignoredRouteSelectors: Set<KClass<*>> = PluginConfigData.DEFAULT.ignoredRouteSelectors
 
 
+    /**
+     * The format of the generated api-spec
+     */
+    var outputFormat: OutputFormat = PluginConfigData.DEFAULT.outputFormat
+
+
     /**
      * Invoked after generating the openapi-spec. Can be to e.g. further customize the spec.
      */
@@ -160,6 +172,7 @@ class PluginConfigDsl {
             },
             specConfigs = mutableMapOf(),
             postBuild = merge(base.postBuild, postBuild),
+            outputFormat = outputFormat
         ).also {
             specConfigs.forEach { (specId, config) ->
                 it.specConfigs[specId] = config.build(it)

diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/routing/ApiSpec.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/routing/ApiSpec.kt
@@ -1,28 +1,33 @@
 package io.github.smiley4.ktorswaggerui.routing
 
+import io.github.smiley4.ktorswaggerui.data.OutputFormat
 import io.github.smiley4.ktorswaggerui.data.SwaggerUIData
 
 object ApiSpec {
 
     var swaggerUiConfig: SwaggerUIData = SwaggerUIData.DEFAULT
 
-    private val apiSpecs = mutableMapOf<String, String>()
+    private val apiSpecs = mutableMapOf<String, Pair<String, OutputFormat>>()
 
-    fun setAll(specs: Map<String, String>) {
+    fun setAll(specs: Map<String, Pair<String, OutputFormat>>) {
         apiSpecs.clear()
         apiSpecs.putAll(specs)
     }
 
-    fun set(name: String, spec: String) {
+    fun set(name: String, spec: Pair<String, OutputFormat>) {
         apiSpecs[name] = spec
     }
 
     fun get(name: String): String {
-        return apiSpecs[name] ?: throw NoSuchElementException("No api-spec with name '$name' registered.")
+        return apiSpecs[name]?.first ?: throw NoSuchElementException("No api-spec with name '$name' registered.")
+    }
+
+    fun getFormat(name: String): OutputFormat {
+        return apiSpecs[name]?.second ?: throw NoSuchElementException("No api-spec with name '$name' registered.")
     }
 
     fun getAll(): Map<String, String> {
-        return apiSpecs
+        return apiSpecs.mapValues { it.value.first }
     }
 
 }
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/routing/routing.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/routing/routing.kt
@@ -2,6 +2,7 @@ package io.github.smiley4.ktorswaggerui.routing
 
 import io.github.smiley4.ktorswaggerui.SWAGGER_UI_WEBJARS_VERSION
 import io.github.smiley4.ktorswaggerui.SwaggerUI
+import io.github.smiley4.ktorswaggerui.data.OutputFormat
 import io.github.smiley4.ktorswaggerui.data.SwaggerUIData
 import io.github.smiley4.ktorswaggerui.data.SwaggerUiSort
 import io.github.smiley4.ktorswaggerui.data.SwaggerUiSyntaxHighlight
@@ -19,7 +20,11 @@ import io.ktor.server.routing.*
 fun Route.openApiSpec(specId: String = PluginConfigDsl.DEFAULT_SPEC_ID) {
     route({ hidden = true }) {
         get {
-            call.respondText(ContentType.Application.Json, HttpStatusCode.OK) { ApiSpec.get(specId) }
+            val contentType = when(ApiSpec.getFormat(specId)) {
+                OutputFormat.JSON -> ContentType.Application.Json
+                OutputFormat.YAML -> ContentType.Text.Plain
+            }
+            call.respondText(contentType, HttpStatusCode.OK) { ApiSpec.get(specId) }
         }
     }
 }

diff --git a/ktor-swagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/misc/RoutingTests.kt b/ktor-swagger-ui/src/test/kotlin/io/github/smiley4/ktorswaggerui/misc/RoutingTests.kt
@@ -1,11 +1,13 @@
 package io.github.smiley4.ktorswaggerui.misc
 
 import io.github.smiley4.ktorswaggerui.SwaggerUI
+import io.github.smiley4.ktorswaggerui.data.OutputFormat
 import io.github.smiley4.ktorswaggerui.routing.openApiSpec
 import io.github.smiley4.ktorswaggerui.routing.swaggerUI
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.string.shouldContain
 import io.kotest.matchers.string.shouldNotBeEmpty
+import io.kotest.matchers.string.shouldStartWith
 import io.ktor.client.HttpClient
 import io.ktor.client.request.get
 import io.ktor.client.statement.bodyAsText
@@ -49,21 +51,61 @@ class RoutingTests {
             it.status shouldBe HttpStatusCode.OK
             it.contentType shouldBe ContentType.Application.Json
             it.body.shouldNotBeEmpty()
+            it.body shouldStartWith "{\n  \"openapi\" : \"3.1.0\","
         }
     }
 
-    private fun swaggerUITestApplication(block: suspend TestContext.() -> Unit) {
+
+    @Test
+    fun basicRoutingYml() = swaggerUITestApplication(OutputFormat.YAML) {
+        get("hello").also {
+            it.status shouldBe HttpStatusCode.OK
+            it.body shouldBe "Hello Test"
+        }
+        get("/").also {
+            it.status shouldBe HttpStatusCode.NotFound
+        }
+        get("/swagger").also {
+            it.status shouldBe HttpStatusCode.OK
+            it.contentType shouldBe ContentType.Text.Html
+            it.body.shouldNotBeEmpty()
+        }
+        get("/swagger/index.html").also {
+            it.status shouldBe HttpStatusCode.OK
+            it.contentType shouldBe ContentType.Text.Html
+            it.body.shouldNotBeEmpty()
+        }
+        get("/swagger/swagger-initializer.js").also {
+            it.status shouldBe HttpStatusCode.OK
+            it.contentType shouldBe ContentType.Application.JavaScript
+            it.body shouldContain "url: \"/api.yml\""
+        }
+        get("/api.yml").also {
+            it.status shouldBe HttpStatusCode.OK
+            it.contentType shouldBe ContentType.Text.Plain.withParameter("charset", "utf-8")
+            it.body.shouldNotBeEmpty()
+            it.body shouldStartWith "openapi: 3.1.0\n"
+        }
+    }
+
+    private fun swaggerUITestApplication(format: OutputFormat = OutputFormat.JSON, block: suspend TestContext.() -> Unit) {
         testApplication {
             val client = createClient {
                 this.followRedirects = followRedirects
             }
-            install(SwaggerUI)
+            install(SwaggerUI) {
+                outputFormat = format
+            }
             routing {
-                route("api.json") {
+                val routeSuffix = when(format) {
+                    OutputFormat.JSON -> "json"
+                    OutputFormat.YAML -> "yml"
+                }
+                route("api.$routeSuffix") {
                     openApiSpec()
                 }
                 route("swagger") {
-                    swaggerUI("/api.json")
+                    swaggerUI("/api.$routeSuffix")
                 }
                 get("hello") {
                     call.respondText("Hello Test")