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) { func TestGenerate_AddApiDoc(t *testing.T) {
type Category struct { type Category struct {
ID int64 `json:"id" description:"分类ID" eg:"123" binding:"required,min=10,max=100"` 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"` Name string `json:"name" description:"分类名称" eg:"baichaqinghuan" binding:"required,min=8"`
} }
type Product struct { type Product struct {

42
openapi/schema.go
View File

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