api-doc/common.go

// Package api_doc ...
//
// Description : api_doc ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 2024-12-24 10:52
package api_doc

import (
	"fmt"
	"git.zhangdeman.cn/gateway/api-doc/define"
	"git.zhangdeman.cn/zhangdeman/consts"
	"strings"
)

// GetUriPathParamList 获取uri参数列表
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 10:52 2024/12/24
func GetUriPathParamList(uriPath string) []*define.ParamConfig {
	var (
		paramList []string
		result    = make([]*define.ParamConfig, 0)
	)
	if paramList = define.UriParamRegexp.FindAllString(uriPath, -1); len(paramList) == 0 {
		return result
	}
	for _, param := range paramList {
		result = append(result, &define.ParamConfig{
			Location:    consts.RequestDataLocationUriPath.String(),
			Path:        strings.TrimRight(strings.TrimLeft(param, "{"), "}"),
			Type:        consts.DataTypeString.String(),
			Title:       param,
			Description: param,
			Required:    true,
		})
	}
	return result
}

// GetDataType 将文档配置的数据类型转换为归一化处理后的数据类型
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 11:52 2024/12/24
func GetDataType(docParamType string, formatType string) consts.DataType {
	docParamType = strings.ToLower(docParamType)
	formatType = strings.ToLower(formatType)
	if len(formatType) == 0 {
		formatType = docParamType
	}
	switch docParamType {
	case "integer":
		if formatType == "int64" {
			return consts.DataTypeInt
		}
		return consts.DataTypeUint
	case "string":
		return consts.DataTypeString
	case "object":
		return consts.DataTypeMapStrAny
	case "boolean":
		return consts.DataTypeBool
	case "number", "float", "double", "float32", "float64":
		return consts.DataTypeFloat
	case "array":
		if formatType == "integer" {
			return consts.DataTypeSliceInt
		} else if formatType == "string" {
			return consts.DataTypeSliceString
		} else {
			return consts.DataTypeSliceAny
		}
	default:
		return consts.DataTypeAny
	}
}

// GetParamLocation 获取参数位置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:02 2024/12/24
func GetParamLocation(docParamLocation string) consts.RequestDataLocation {
	docParamLocation = strings.ToLower(docParamLocation)
	switch docParamLocation {
	case "query":
		return consts.RequestDataLocationQuery
	case "header":
		return consts.RequestDataLocationHeader
	case "cookie":
		return consts.RequestDataLocationCookie
	case "body":
		return consts.RequestDataLocationBody
	case "path":
		return consts.RequestDataLocationUriPath
	default:
		return consts.RequestDataLocationQuery
	}
}

// GetRealDefinitionsKey 通过schema下的 $ref 获取真实的 definitions key
func GetRealDefinitionsKey(ref string) string {
	return strings.TrimPrefix(ref, "#/definitions/")
}

// GetRealResponseKey 通过schema下的 $ref 获取真实的 response key
func GetRealResponseKey(ref string) string {
	return strings.TrimPrefix(ref, "#/responses/")
}

// GetSuccessResponseConfig 获取成功的响应配置
func GetSuccessResponseConfig(resultConfig map[string]*define.SwaggerPathConfigResponse) *define.SwaggerPathConfigResponse {
	for httpCode := 200; httpCode <= 299; httpCode++ {
		if cfg := resultConfig[fmt.Sprintf("%d", httpCode)]; nil != cfg {
			return cfg
		}
	}
	return nil
}

// DataTypeIsArray 判断数据类型是否为数组
func DataTypeIsArray(docDataType string) bool {
	return strings.ToLower(docDataType) == "array"
}

// ExpandArrayParam 展开详细的数组配置
func ExpandArrayParam(swaggerDoc *define.Swagger, ref string, rootPath string) []*define.ParamConfig {
	pathPrefix := ""
	if len(rootPath) > 0 {
		pathPrefix = rootPath + "."
	}
	res := make([]*define.ParamConfig, 0)
	for itemKey, itemConfig := range swaggerDoc.Definitions[GetRealDefinitionsKey(ref)].Properties {
		res = append(res, &define.ParamConfig{
			Location:    consts.RequestDataLocationBody.String(),
			Path:        pathPrefix + "{{#idx#}}." + itemKey,
			Type:        GetDataType(itemConfig.Type, "").String(),
			Title:       pathPrefix + itemKey,
			Description: pathPrefix + itemKey,
			Required:    false,
		})
	}
	return res
}

// ExpandArrayResult 展开返回值配置
func ExpandArrayResult(swaggerDoc *define.Swagger, ref string, rootPath string) []*define.ResultConfig {
	pathPrefix := ""
	if len(rootPath) > 0 && rootPath != consts.ResponseDataLocationBodyRoot.String() {
		pathPrefix = rootPath + "."
	}
	ref = GetRealDefinitionsKey(ref)
	res := make([]*define.ResultConfig, 0)
	for itemKey, itemConfig := range swaggerDoc.Definitions[ref].Properties {
		res = append(res, &define.ResultConfig{
			Location:    consts.ResponseDataLocationBody.String(),
			Path:        pathPrefix + "{{#idx#}}." + itemKey,
			Type:        GetDataType(itemConfig.Type, "").String(),
			Title:       pathPrefix + itemKey,
			Description: pathPrefix + itemKey,
		})
	}
	return res
}