Merge pull request '增加枚举值描述解析' (#12) from feature/support_enum_desc into master

Reviewed-on: #12

define/openapi.go

@@ -130,6 +130,7 @@ type Schema struct {
 	Properties       map[string]*Property `json:"properties,omitempty"`         // 数据字段 => 数据规则
 	Required         []string             `json:"required,omitempty"`           // 必传属性列表
 	Enum             []any                `json:"enum,omitempty"`               // 枚举值列表
+	XEnumDescription map[string]string    `json:"x-enumDescriptions,omitempty"` // 枚举值描述的扩展, redoc-free支持
 	Type             string               `json:"type,omitempty"`               // 类型
 	Items            *PropertyXOf         `json:"items,omitempty"`              // items 必须存在如果 type 的值是 array。
 	Ref              string               `json:"$ref,omitempty"`               // 类型引用
@@ -148,6 +149,7 @@ type Property struct {
 	Type                 string               `json:"type,omitempty"`                 // 数据类型, swagger本身的定义
 	Format               string               `json:"format,omitempty"`               // 对应编程语言中的数据类型描述
 	Enum                 []any                `json:"enum,omitempty"`                 // 枚举值列表
+	XEnumDescription     map[string]string    `json:"x-enumDescriptions,omitempty"`   // 枚举值描述的扩展, redoc-free支持
 	Default              any                  `json:"default,omitempty"`              // 默认值 : 不同于 JSON Schema，这个值必须符合定义与相同级别的 Schema 对象 中定义的类型，比如 type 是 string，那么 default 可以是 "foo" 但不能是 1。
 	Description          string               `json:"description,omitempty"`          // 数据描述, CommonMark syntax可以被用来呈现富文本格式.
 	Maximum              *int64               `json:"maximum,omitempty"`              // 最大值

define/tag.go

@@ -32,4 +32,5 @@ const (
 	TagContentType         = "content_type"
 	TagOutputContentType   = "output_content_type"
 	TagNameOmitempty       = "omitempty"
+	TagNameEnumDescription = "enum-desc" // 枚举值描述: enum1:enum1-desc||enum2:enum2-desc
 )

generate.go

@@ -359,6 +359,8 @@ func (g *Generate) ParseReadConfigParam(requestCfg *define.UriBaseConfig, baseRe
 					Type:             convertBaseType,
 					Format:           realInputTypeFormat,
 					Default:          ParseStructFieldTag.GetDefaultValue(inputType.Field(i)),
+					Enum:             ValidateRule.Enum(inputType.Field(i)),
+					XEnumDescription: ParseStructFieldTag.EnumDescription(inputType.Field(i)),
 				},
 				AllowEmptyValue: false,
 				Style:           "",
@@ -406,6 +408,8 @@ func (g *Generate) ParseReadConfigParam(requestCfg *define.UriBaseConfig, baseRe
 					Items:            nil,
 					Ref:              "",
 					Format:           realInputTypeFormat,
+					Enum:             ValidateRule.Enum(inputType.Field(i)),
+					XEnumDescription: ParseStructFieldTag.EnumDescription(inputType.Field(i)),
 				},
 				AllowEmptyValue: false,
 				Style:           "",
@@ -523,6 +527,8 @@ func (g *Generate) AddComponentsSchema(rootSchemaName string, pkgPath string, in
 					g.docData.Components.Schemas[schemaName].Properties[propertyName] = &define.Property{
 						Type:             convertBaseType,
 						Format:           inputType.Field(i).Type.String(),
+						Enum:             ValidateRule.Enum(inputType.Field(i)),
+						XEnumDescription: ParseStructFieldTag.EnumDescription(inputType.Field(i)),
 						Maximum:          ValidateRule.Maximum(inputType.Field(i)),
 						Minimum:          ValidateRule.Minimum(inputType.Field(i)),
 						Default:          ParseStructFieldTag.GetDefaultValue(inputType.Field(i)),
@@ -627,6 +633,7 @@ func (g *Generate) handleAnonymousField(schemaName string, field reflect.StructF
 					Type:             baseConvertType,
 					Format:           itemField.Type.String(),
 					Enum:             ValidateRule.Enum(itemField),
+					XEnumDescription: ParseStructFieldTag.EnumDescription(itemField),
 					Default:          ParseStructFieldTag.GetDefaultValue(handleType.Field(i)),
 					Description:      ParseStructFieldTag.GetParamDesc(handleType.Field(i)),
 				}

struct_field.go

@@ -150,3 +150,31 @@ func (psf parseStructFieldTag) Summary(structField reflect.StructField) string {
 	}
 	return paramName
 }
+
+// EnumDescription .枚举值详细描述
+//
+// Author : go_developer@163.com<白茶清欢>
+//
+// Date : 22:40 2025/2/18
+func (psf parseStructFieldTag) EnumDescription(structField reflect.StructField) map[string]string {
+	defaultTagList := []string{define.TagNameEnumDescription}
+	res := map[string]string{}
+	for _, tag := range defaultTagList {
+		if tagVal, exist := structField.Tag.Lookup(tag); exist && len(tagVal) > 0 {
+			tagVal = strings.ReplaceAll(tagVal, "###", "`")
+			enumList := strings.Split(tagVal, "||")
+			for _, enum := range enumList {
+				enumArr := strings.Split(enum, ":")
+				if len(enumArr) < 2 {
+					continue
+				}
+				res[enumArr[0]] = strings.Join(enumArr[1:], ":")
+			}
+			return res
+		}
+	}
+	if len(res) == 0 {
+		return nil
+	}
+	return res
+}