KTOR-8074 Swagger: Add deepLinking configuration (#4607)

ktorio · Jan 16, 2025 · 1e91560 · 1e91560
1 parent 7a4b63c
commit 1e91560
Showing 4 changed files with 55 additions and 0 deletions.
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](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/swagger-ui-dist@5.17.12/swagger-ui.css" rel="stylesheet">
+                <link href="https://unpkg.com/swagger-ui-dist@5.17.12/favicon-32x32.png" rel="icon" type="image/x-icon">
+              </head>
+              <body>
+                <div id="swagger-ui"></div>
+                <script src="https://unpkg.com/swagger-ui-dist@5.17.12/swagger-ui-bundle.js" crossorigin="anonymous"></script>
+                <script src="https://unpkg.com/swagger-ui-dist@5.17.12/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
@@ -133,6 +177,7 @@ class SwaggerTest {
                 window.ui = SwaggerUIBundle({
                     url: '/swagger/documentation.yaml',
                     dom_id: '#swagger-ui',
+                    deepLinking: false,
                     presets: [
                         SwaggerUIBundle.presets.apis,
                         SwaggerUIStandalonePreset