Merge pull request #221 from Shun-Arahata/feature/add-x-displayname-support

Add support for Redoc's x-displayName extension to tag configuration

Author: SMILEY4

examples/src/main/kotlin/io/github/smiley4/ktoropenapi/examples/CompleteConfig.kt

@@ -95,11 +95,13 @@ private fun Application.myModule() {
                 description = "routes to manage users"
                 externalDocUrl = "example.com"
                 externalDocDescription = "Users documentation"
+                displayName = "User Management"  // Redoc's x-displayName extension
             }
             tag("documents") {
                 description = "routes to manage documents"
                 externalDocUrl = "example.com"
                 externalDocDescription = "Document documentation"
+                displayName = "Document Management"  // Redoc's x-displayName extension
             }
         }
         schemas {

ktor-openapi/src/main/kotlin/io/github/smiley4/ktoropenapi/builder/openapi/TagBuilder.kt

@@ -18,6 +18,9 @@ internal class TagBuilder(
             if(tag.externalDocUrl != null && tag.externalDocDescription != null) {
                 it.externalDocs = tagExternalDocumentationBuilder.build(tag.externalDocUrl, tag.externalDocDescription)
             }
+            if(tag.displayName != null) {
+                it.extensions = mapOf("x-displayName" to tag.displayName)
+            }
         }
 
 }

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

@@ -29,12 +29,19 @@ class TagConfig internal constructor(
      */
     var externalDocUrl: String? = null
 
+    /**
+     * Custom display name for the tag. Maps to Redoc's x-displayName extension.
+     * When defined, this name is used instead of the default name in the navigation sidebar and section headings.
+     */
+    var displayName: String? = null
+
 
     internal fun build(base: TagData) = TagData(
         name = name,
         description = merge(base.description, description),
         externalDocDescription = merge(base.externalDocDescription, externalDocDescription),
-        externalDocUrl = merge(base.externalDocUrl, externalDocUrl)
+        externalDocUrl = merge(base.externalDocUrl, externalDocUrl),
+        displayName = merge(base.displayName, displayName)
     )
 
 }

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

@@ -7,15 +7,21 @@ internal data class TagData(
     val name: String,
     val description: String?,
     val externalDocDescription: String?,
-    val externalDocUrl: String?
+    val externalDocUrl: String?,
+    /**
+     * Custom display name for the tag. Maps to Redoc's x-displayName extension.
+     * When defined, this name is used instead of the default name in the navigation sidebar and section headings.
+     */
+    val displayName: String?
 ) {
 
     companion object {
         val DEFAULT = TagData(
             name = "",
             description = null,
             externalDocDescription = null,
-            externalDocUrl = null
+            externalDocUrl = null,
+            displayName = null
         )
     }
 }

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

@@ -40,6 +40,18 @@ class TagsBuilderTest : StringSpec({
         }
     }
 
+    "tag object with x-displayName" {
+        buildTagObject("test-tag-123") {
+            description = "Description of tag"
+            displayName = "Custom Display Name"
+        }.also { tag ->
+            tag.name shouldBe "test-tag-123"
+            tag.description shouldBe "Description of tag"
+            tag.extensions.shouldNotBeNull()
+            tag.extensions["x-displayName"] shouldBe "Custom Display Name"
+        }
+    }
+
 }) {
 
     companion object {