api-doc/struct_field.go

// Package api_doc ...
//
// Description : api_doc ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 2025-02-12 22:15
package api_doc

import (
	"git.zhangdeman.cn/gateway/api-doc/define"
	"reflect"
	"strconv"
	"strings"
)

var (
	ParseStructFieldTag = parseStructFieldTag{}
)

type parseStructFieldTag struct {
}

// GetParamName 获取参数名称
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 21:58 2025/2/11
func (psf parseStructFieldTag) GetParamName(structField reflect.StructField) string {
	paramNameTagList := []string{
		define.TagJson, define.TagForm,
		define.TagXml, define.TagYaml,
		define.TagYml,
	}
	for _, tag := range paramNameTagList {
		tagVal := structField.Tag.Get(tag)
		tagVal = strings.TrimSuffix(strings.TrimPrefix(tagVal, define.TagNameOmitempty+","), ","+define.TagNameOmitempty)
		tagVal = strings.Trim(tagVal, ",")
		if tagVal != "" && tagVal != define.TagNameOmitempty {
			return tagVal
		}
	}
	// 未设置相关字段, 则字段名即为参数名
	return structField.Name
}

// GetParamDesc ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 22:01 2025/2/11
func (psf parseStructFieldTag) GetParamDesc(structField reflect.StructField) string {
	descTagList := []string{define.TagDc, define.TagDesc, define.TagDescription}
	for _, tag := range descTagList {
		tagVal := structField.Tag.Get(tag)
		if tagVal != "" {
			return strings.ReplaceAll(tagVal, "###", "`")
		}
	}
	// 没有显示的设置参数描述, 则使用参数名作为参数描述
	return psf.GetParamName(structField)
}

// GetDefaultValue 获取默认值
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 22:05 2025/2/11
func (psf parseStructFieldTag) GetDefaultValue(structField reflect.StructField) any {
	defaultTagList := []string{define.TagD, define.TagDefault}
	fieldType := structField.Type.Kind().String()
	for _, tag := range defaultTagList {
		val, exist := structField.Tag.Lookup(tag)
		val = strings.TrimSpace(val)
		if !exist || len(val) == 0 {
			continue
		}
		if strings.HasPrefix(fieldType, "int") {
			i, _ := strconv.Atoi(val)
			return i
		}
		if strings.HasPrefix(fieldType, "uint") {
			uintVal, _ := strconv.ParseUint(val, 10, 64)
			return uintVal
		}
		if strings.HasPrefix(fieldType, "float") {
			floatVal, _ := strconv.ParseFloat(val, 64)
			return floatVal
		}
		if strings.HasPrefix(fieldType, "string") {
			return val
		}
		if strings.HasPrefix(fieldType, "bool") {
			if val == "true" {
				return true
			} else {
				return false
			}
		}
		return val
	}
	return nil
}

// GetValidateRule 获取验证规则
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 15:30 2025/2/13
func (psf parseStructFieldTag) GetValidateRule(structField reflect.StructField) string {
	defaultTagList := []string{define.TagValidate, define.TagBinding}
	for _, tag := range defaultTagList {
		if tagVal, exist := structField.Tag.Lookup(tag); exist && len(tagVal) > 0 {
			return tagVal
		}
	}
	return ""
}

// Deprecated 是否弃用
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 21:12 2025/2/13
func (psf parseStructFieldTag) Deprecated(structField reflect.StructField) bool {
	defaultTagList := []string{define.TagDeprecated}
	for _, tag := range defaultTagList {
		if tagVal, exist := structField.Tag.Lookup(tag); exist && (tagVal == "1" || strings.ToLower(tagVal) == "true") {
			return true
		}
	}
	return false
}

// Summary 摘要信息
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 15:15 2025/2/14
func (psf parseStructFieldTag) Summary(structField reflect.StructField) string {
	defaultTagList := []string{define.TagSummary}
	for _, tag := range defaultTagList {
		if tagVal, exist := structField.Tag.Lookup(tag); exist && len(tagVal) > 0 {
			return tagVal
		}
	}
	paramName := psf.GetParamName(structField)
	if paramName == "-" {
		return ""
	}
	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
}

// GetExampleValue 示例值
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:42 2025/2/20
func (psf parseStructFieldTag) GetExampleValue(structField reflect.StructField) any {
	descTagList := []string{define.TagEg, define.TagExample}
	fieldType := structField.Type.Kind().String()
	for _, tag := range descTagList {
		val := strings.TrimSpace(structField.Tag.Get(tag))
		if val == "" {
			continue
		}
		if strings.HasPrefix(fieldType, "int") {
			i, _ := strconv.Atoi(val)
			return i
		}
		if strings.HasPrefix(fieldType, "uint") {
			uintVal, _ := strconv.ParseUint(val, 10, 64)
			return uintVal
		}
		if strings.HasPrefix(fieldType, "float") {
			floatVal, _ := strconv.ParseFloat(val, 64)
			return floatVal
		}
		if strings.HasPrefix(fieldType, "string") {
			return val
		}
		if strings.HasPrefix(fieldType, "bool") {
			if val == "true" {
				return true
			} else {
				return false
			}
		}
		return val
	}
	return nil
}