Add deepLinking configuration variable to Swagger plugin

ktorio · Jan 15, 2025 · 8e1a2a9 · 8e1a2a9
1 parent 01abaa9
commit 8e1a2a9
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 1 deletion.
diff --git a/ktor-server/ktor-server-plugins/ktor-server-swagger/api/ktor-server-swagger.api b/ktor-server/ktor-server-plugins/ktor-server-swagger/api/ktor-server-swagger.api
@@ -1,9 +1,11 @@
 public final class io/ktor/server/plugins/swagger/SwaggerConfig {
 	public fun <init> ()V
 	public final fun customStyle (Ljava/lang/String;)V
+	public final fun getDeepLinking ()Z
 	public final fun getFaviconLocation ()Ljava/lang/String;
 	public final fun getPackageLocation ()Ljava/lang/String;
 	public final fun getVersion ()Ljava/lang/String;
+	public final fun setDeepLinking (Z)V
 	public final fun setFaviconLocation (Ljava/lang/String;)V
 	public final fun setPackageLocation (Ljava/lang/String;)V
 	public final fun setVersion (Ljava/lang/String;)V

diff --git a/...ktor-server-plugins/ktor-server-swagger/jvm/src/io/ktor/server/plugins/swagger/Swagger.kt b/...ktor-server-plugins/ktor-server-swagger/jvm/src/io/ktor/server/plugins/swagger/Swagger.kt
@@ -110,6 +110,7 @@ window.onload = function() {
     window.ui = SwaggerUIBundle({
         url: '$fullPath/$apiUrl',
         dom_id: '#swagger-ui',
+        deepLinking: ${config.deepLinking},
         presets: [
             SwaggerUIBundle.presets.apis,
             SwaggerUIStandalonePreset

diff --git a/...erver-plugins/ktor-server-swagger/jvm/src/io/ktor/server/plugins/swagger/SwaggerConfig.kt b/...erver-plugins/ktor-server-swagger/jvm/src/io/ktor/server/plugins/swagger/SwaggerConfig.kt
@@ -30,6 +30,13 @@ public class SwaggerConfig {
     public var packageLocation: String = "https://unpkg.com/swagger-ui-dist"
 
     /**
+     * Whether to allow deep linking in Swagger UI, as described here: https://swagger.io/docs/open-source-tools/swagger-ui/usage/deep-linking/
+     *
+     * Defaults to `false`.
+     */
+    public var deepLinking: Boolean = false
+
+    /*
      * Swagger favicon location
      */
     public var faviconLocation: String = "https://unpkg.com/swagger-ui-dist@$version/favicon-32x32.png"

diff --git a/...server-plugins/ktor-server-swagger/jvm/test/io/ktor/server/plugins/swagger/SwaggerTest.kt b/...server-plugins/ktor-server-swagger/jvm/test/io/ktor/server/plugins/swagger/SwaggerTest.kt
@@ -36,6 +36,49 @@ class SwaggerTest {
                 window.ui = SwaggerUIBundle({
                     url: '/swagger/documentation.yaml',
                     dom_id: '#swagger-ui',
+                    deepLinking: false,
+                    presets: [
+                        SwaggerUIBundle.presets.apis,
+                        SwaggerUIStandalonePreset
+                    ],
+                    layout: 'StandaloneLayout'
+                });
+            }</script>
+              </body>
+            </html>
+
+            """.trimIndent(),
+            response
+        )
+    }
+
+    @Test
+    fun testSwaggerAllowDeepLinking() = testApplication {
+        routing {
+            swaggerUI("swagger") {
+                deepLinking = true
+            }
+        }
+
+        val response = client.get("/swagger").bodyAsText()
+        assertEquals(
+            """
+            <!DOCTYPE html>
+            <html>
+              <head>
+                <title>Swagger UI</title>
+                <link href="https://unpkg.com/[email protected]/swagger-ui.css" rel="stylesheet">
+                <link href="https://unpkg.com/[email protected]/favicon-32x32.png" rel="icon" type="image/x-icon">
+              </head>
+              <body>
+                <div id="swagger-ui"></div>
+                <script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin="anonymous"></script>
+                <script src="https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js" crossorigin="anonymous"></script>
+                <script>window.onload = function() {
+                window.ui = SwaggerUIBundle({
+                    url: '/swagger/documentation.yaml',
+                    dom_id: '#swagger-ui',
+                    deepLinking: true,
                     presets: [
                         SwaggerUIBundle.presets.apis,
                         SwaggerUIStandalonePreset
@@ -77,6 +120,7 @@ class SwaggerTest {
                 window.ui = SwaggerUIBundle({
                     url: '/swagger/documentation.yaml',
                     dom_id: '#swagger-ui',
+                    deepLinking: false,
                     presets: [
                         SwaggerUIBundle.presets.apis,
                         SwaggerUIStandalonePreset
@@ -101,7 +145,7 @@ class SwaggerTest {
 
         val response = client.get("/openapi/documentation.yaml")
         val body = response.bodyAsText()
-        assertEquals("application/yaml", response.contentType().toString())
+        assertEquals("application/yaml; charset=UTF-8", response.contentType().toString())
         assertEquals("hello:\n  world".filter { it.isLetterOrDigit() }, body.filter { it.isLetterOrDigit() })
     }
 
@@ -133,6 +177,7 @@ class SwaggerTest {
                 window.ui = SwaggerUIBundle({
                     url: '/swagger/documentation.yaml',
                     dom_id: '#swagger-ui',
+                    deepLinking: false,
                     presets: [
                         SwaggerUIBundle.presets.apis,
                         SwaggerUIStandalonePreset