feat: Add x-enum-descriptions to generated Swagger documentation for …

…Enums (#1878)

This commit adds support for the x-enum-descriptions extension in the
generated Swagger documentation.

It aligns the order of enum comments with enum variable names and
outputs them as a new x-enum-descriptions array.
This change ensures that enum descriptions are clearly defined and ordered alongside the enum values and variable names.

enums.go

@@ -1,8 +1,9 @@
 package swag
 
 const (
-	enumVarNamesExtension = "x-enum-varnames"
-	enumCommentsExtension = "x-enum-comments"
+	enumVarNamesExtension     = "x-enum-varnames"
+	enumCommentsExtension     = "x-enum-comments"
+	enumDescriptionsExtension = "x-enum-descriptions"
 )
 
 // EnumValue a model to record an enum consts variable

parser.go

@@ -1318,11 +1318,13 @@ func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)
 	if len(typeSpecDef.Enums) > 0 {
 		var varnames []string
 		var enumComments = make(map[string]string)
+		var enumDescriptions = make([]string, 0, len(typeSpecDef.Enums))
 		for _, value := range typeSpecDef.Enums {
 			definition.Enum = append(definition.Enum, value.Value)
 			varnames = append(varnames, value.key)
 			if len(value.Comment) > 0 {
 				enumComments[value.key] = value.Comment
+				enumDescriptions = append(enumDescriptions, value.Comment)
 			}
 		}
 		if definition.Extensions == nil {
@@ -1331,6 +1333,7 @@ func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef) (*Schema, error)
 		definition.Extensions[enumVarNamesExtension] = varnames
 		if len(enumComments) > 0 {
 			definition.Extensions[enumCommentsExtension] = enumComments
+			definition.Extensions[enumDescriptionsExtension] = enumDescriptions
 		}
 	}
 

testdata/enums/expected.json

@@ -102,6 +102,10 @@
                             "A": "AAA",
                             "B": "BBB"
                         },
+                        "x-enum-descriptions": [
+                            "AAA",
+                            "BBB"
+                        ],
                         "x-enum-varnames": [
                             "None",
                             "A",
@@ -128,6 +132,12 @@
                             "Mask3": "Mask3",
                             "Mask4": "Mask4"
                         },
+                        "x-enum-descriptions": [
+                            "Mask1",
+                            "Mask2",
+                            "Mask3",
+                            "Mask4"
+                        ],
                         "x-enum-varnames": [
                             "Mask1",
                             "Mask2",
@@ -155,6 +165,11 @@
                             "Student": "student",
                             "Teacher": "teacher"
                         },
+                        "x-enum-descriptions": [
+                            "teacher",
+                            "student",
+                            "Other"
+                        ],
                         "x-enum-varnames": [
                             "Teacher",
                             "Student",
@@ -224,6 +239,11 @@
                             "Student": "student",
                             "Teacher": "teacher"
                         },
+                        "x-enum-descriptions": [
+                            "teacher",
+                            "student",
+                            "Other"
+                        ],
                         "x-enum-varnames": [
                             "Teacher",
                             "Student",
@@ -256,6 +276,10 @@
                 "A": "AAA",
                 "B": "BBB"
             },
+            "x-enum-descriptions": [
+                "AAA",
+                "BBB"
+            ],
             "x-enum-varnames": [
                 "None",
                 "A",
@@ -280,6 +304,12 @@
                 "Mask3": "Mask3",
                 "Mask4": "Mask4"
             },
+            "x-enum-descriptions": [
+                "Mask1",
+                "Mask2",
+                "Mask3",
+                "Mask4"
+            ],
             "x-enum-varnames": [
                 "Mask1",
                 "Mask2",
@@ -317,6 +347,11 @@
                 "Student": "student",
                 "Teacher": "teacher"
             },
+            "x-enum-descriptions": [
+                "teacher",
+                "student",
+                "Other"
+            ],
             "x-enum-varnames": [
                 "Teacher",
                 "Student",