zhangdeman/api-doc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 枚举值增加 x-enum-descriptions 用于标记枚举值含义

Browse Source
This commit is contained in:
白茶清欢
2026-01-06 22:42:29 +08:00
parent a0090ad524
commit 5d86daadeb
3 changed files with 25 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
openapi/generate_test.go
View File

@@ -20,6 +20,7 @@ import (
func TestGenerate_AddApiDoc(t *testing.T) {
type Category struct {
ID int64 `json:"id" description:"分类ID" eg:"123" binding:"required,min=10,max=100"`
Sex string `json:"sex" dc:"性别" binding:"required,oneof=man woman" enum-desc:"man:男||woman:女"`
Name string `json:"name" description:"分类名称" eg:"baichaqinghuan" binding:"required,min=8"`
}
type Product struct {

42
openapi/schema.go
View File

@@ -11,30 +11,29 @@ import (
"reflect"
"time"
"git.zhangdeman.cn/zhangdeman/api-doc/define"
"git.zhangdeman.cn/zhangdeman/api-doc/util"
"github.com/getkin/kin-openapi/openapi3"
)
// StructFieldInfo 结构体字段信息
type StructFieldInfo struct {
IsString bool `json:"is_string" dc:"是否字符串"`
Name string `json:"name" dc:"结构体字段名"`
JSONName string `json:"json_name" dc:"json tag"`
Type reflect.Type `json:"type" dc:"字段类型"`
Description string `json:"description" dc:"参数描述"`
Example any `json:"example" dc:"示例值"`
Default any `json:"default" dc:"默认值"`
Required bool `json:"required" dc:"是否必传"`
Min *float64 `json:"min" dc:"最小值"`
Max *float64 `json:"max" dc:"最大值"`
MinLength *float64 `json:"min_length" dc:"最小长度"`
MaxLength *float64 `json:"max_length" dc:"最大长度"`
Pattern string `json:"pattern" dc:"模式"`
Format string `json:"format" dc:"格式"`
Enum []any `json:"enum" dc:"枚举值列表"`
EnumDesc []define.EnumValue `json:"enum_desc" dc:"枚举值详细描述"`
OmitEmpty bool `json:"omit_empty" dc:"是否可控"`
IsString bool `json:"is_string" dc:"是否字符串"`
Name string `json:"name" dc:"结构体字段名"`
JSONName string `json:"json_name" dc:"json tag"`
Type reflect.Type `json:"type" dc:"字段类型"`
Description string `json:"description" dc:"参数描述"`
Example any `json:"example" dc:"示例值"`
Default any `json:"default" dc:"默认值"`
Required bool `json:"required" dc:"是否必传"`
Min *float64 `json:"min" dc:"最小值"`
Max *float64 `json:"max" dc:"最大值"`
MinLength *float64 `json:"min_length" dc:"最小长度"`
MaxLength *float64 `json:"max_length" dc:"最大长度"`
Pattern string `json:"pattern" dc:"模式"`
Format string `json:"format" dc:"格式"`
Enum []any `json:"enum" dc:"枚举值列表"`
EnumDesc map[string]string `json:"enum_desc" dc:"枚举值详细描述"`
OmitEmpty bool `json:"omit_empty" dc:"是否可控"`
}
// ParseStructField 解析结构体字段信息
@@ -212,9 +211,10 @@ func applyFieldInfoToSchema(schema *openapi3.Schema, info *StructFieldInfo) {
}
if len(info.Enum) > 0 {
schema.Enum = info.Enum
/*for _, item := range info.Enum {
schema.Enum = append(schema.Enum, item.Value)
}*/
if nil == schema.Extensions {
schema.Extensions = map[string]any{}
}
schema.Extensions["x-enum-descriptions"] = info.EnumDesc
}
}

9
util/struct_field.go
View File

@@ -144,9 +144,9 @@ func (psf parseStructFieldTag) Summary(structField reflect.StructField) string {
}
// EnumDescription .枚举值详细描述
func (psf parseStructFieldTag) EnumDescription(structField reflect.StructField) []define.EnumValue {
func (psf parseStructFieldTag) EnumDescription(structField reflect.StructField) map[string]string {
defaultTagList := []string{define.TagNameEnumDescription}
res := make([]define.EnumValue, 0)
res := make(map[string]string)
for _, tag := range defaultTagList {
if tagVal, exist := structField.Tag.Lookup(tag); exist && len(tagVal) > 0 {
tagVal = strings.ReplaceAll(tagVal, "###", "`")
@@ -156,10 +156,7 @@ func (psf parseStructFieldTag) EnumDescription(structField reflect.StructField)
if len(enumArr) < 2 {
continue
}
res = append(res, define.EnumValue{
Value: enumArr[0],
Description: strings.Join(enumArr[1:], ":"),
})
res[enumArr[0]] = strings.Join(enumArr[1:], ":")
}
return res
}