api-doc/swagger/run.go

// Package swagger ...
//
// Description : swagger ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 2024-04-19 18:16
package swagger

import (
	"git.zhangdeman.cn/gateway/api-doc/define"
	"git.zhangdeman.cn/gateway/api-doc/util"
	"git.zhangdeman.cn/zhangdeman/consts"
	"git.zhangdeman.cn/zhangdeman/wrapper"
	"net/http"
	"strings"
)

// Generate 生成文档
//
// Author : zhangdeman001@ke.com<张德满>
//
// Date : 18:17 2024/4/19
func Generate(docConfig *define.SwaggerInput) (*define.Swagger, error) {
	formatDocConfig(docConfig)
	swaggerInfo := &define.Swagger{
		Schemes:     docConfig.Schemes,
		Swagger:     consts.SwaggerDocVersion2,
		Host:        docConfig.Host,
		BasePath:    docConfig.BasePath,
		Info:        docConfig.Info,
		Paths:       map[string]map[string]*define.SwaggerPathConfig{},
		Definitions: map[string]*define.SwaggerDefinition{},
	}
	generatePathConfig(swaggerInfo, docConfig)
	return swaggerInfo, nil
}

// formatDocConfig 格式化填充dock配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 10:54 2024/4/22
func formatDocConfig(docConfig *define.SwaggerInput) {
	if len(docConfig.Schemes) == 0 {
		docConfig.Schemes = []string{
			consts.SchemeHTTP.String(),
		}
	}
	docConfig.Host = wrapper.String(docConfig.Host).ReplaceChar(map[string]string{
		consts.SchemeHTTP.String() + "://":  "",
		consts.SchemeHTTPS.String() + "://": "",
	}).Value()
	for _, itemPath := range docConfig.PathConfigList {
		// 默认请求类型 application/json
		itemPath.ContentType = strings.TrimSpace(itemPath.ContentType)
		itemPath.ContentType = wrapper.TernaryOperator.String(len(itemPath.ContentType) == 0, consts.MimeTypeJson, wrapper.String(itemPath.ContentType)).Value()
		// 默认post请求
		itemPath.Method = strings.TrimSpace(itemPath.Method)
		itemPath.Method = wrapper.TernaryOperator.String(len(itemPath.ContentType) == 0, wrapper.String(strings.ToLower(http.MethodPost)), wrapper.String(strings.ToLower(itemPath.Method))).Value()
		// 默认summary
		itemPath.Summary = strings.TrimSpace(itemPath.Summary)
		itemPath.Summary = wrapper.TernaryOperator.String(len(itemPath.Summary) == 0, wrapper.String("接口 : "+itemPath.Uri), wrapper.String(itemPath.Summary)).Value()
		// 默认标签
		if len(itemPath.TagList) == 0 {
			itemPath.TagList = []string{"未分组"}
		}
		for _, itemParam := range itemPath.ParameterList {
			// 填充默认参数位置
			itemParam.In = strings.TrimSpace(itemParam.In)
			itemParam.In = wrapper.TernaryOperator.String(len(itemParam.In) == 0, wrapper.String(util.GetParameterDefaultLocation(itemPath.Method)), wrapper.String(itemParam.In)).Value()

			// 参数类型没填, 按照字符串处理
			itemParam.Type = strings.TrimSpace(itemParam.Type)
			itemParam.Type = wrapper.TernaryOperator.String(len(itemParam.Type) == 0, wrapper.String(itemParam.Type), wrapper.String(itemParam.Type)).Value()

			// 参数描述
			itemParam.Description = strings.TrimSpace(itemParam.Description)
			itemParam.Description = wrapper.TernaryOperator.String(len(itemParam.Description) == 0, wrapper.String(itemParam.Type+" : "+itemParam.Name), wrapper.String(itemParam.Description)).Value()
		}

		for _, itemResponseConfig := range itemPath.ResponseList {
			for _, itemResponse := range itemResponseConfig.List {
				// 默认返回数据类型
				itemResponse.Type = strings.TrimSpace(itemResponse.Type)
				itemResponse.Type = wrapper.TernaryOperator.String(len(itemResponse.Type) == 0, wrapper.String(consts.DataTypeString), wrapper.String(itemResponse.Type)).Value()
				// 填充默认描述
				itemResponse.Description = strings.TrimSpace(itemResponse.Description)
				itemResponse.Description = wrapper.TernaryOperator.String(len(itemResponse.Description) == 0, wrapper.String(itemResponse.Type+" : "+itemResponse.Field), wrapper.String(itemResponse.Description)).Value()
			}
		}
	}
}

// generatePathConfig 生成接口配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:00 2024/4/22
func generatePathConfig(swaggerInfo *define.Swagger, docConfig *define.SwaggerInput) {
	for _, itemPath := range docConfig.PathConfigList {
		itemPath.Uri = getUri(itemPath.Uri)
		if _, exist := swaggerInfo.Paths[itemPath.Uri]; !exist {
			swaggerInfo.Paths[itemPath.Uri] = map[string]*define.SwaggerPathConfig{}
		}
		// 处理请求类型的配置
		swaggerInfo.Paths[itemPath.Uri][itemPath.Method] = &define.SwaggerPathConfig{
			Description: itemPath.Description,
			Consumes:    []string{itemPath.ContentType},
			Tags:        itemPath.TagList,
			Summary:     itemPath.Summary,
			Parameters:  make([]*define.SwaggerPathConfigParameter, 0),
			Responses:   make(map[string]*define.SwaggerPathConfigResponse),
		}
		// 生成参数配置
		generatePathParameterConfig(swaggerInfo, itemPath)
		// 生成相应配置
		generatePathResponseConfig(swaggerInfo, itemPath)
	}
}

// generatePathParameterConfig 生成接口的参数配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:09 2024/4/22
func generatePathParameterConfig(swaggerInfo *define.Swagger, pathConfig *define.SwaggerPathInput) {
	swaggerInfo.Paths[pathConfig.Uri][pathConfig.Method].Parameters = make([]*define.SwaggerPathConfigParameter, 0)
	hasDealTable := map[string]bool{}

	for _, itemParamInput := range pathConfig.ParameterList {
		if len(itemParamInput.Name) == 0 {
			// 未指定参数名, 忽略
			continue
		}
		// name 可能是 x.x.x 递归数组, 或者 x.x.[].x
		namePath := strings.Split(itemParamInput.Name, ".")
		realParamName := namePath[0]
		parentPath := ""
		if strings.ToUpper(itemParamInput.In) == consts.RequestDataLocationBody.String() && !strings.Contains(realParamName, ".") {
			realParamName = "jsonBody"
			parentPath = strings.ReplaceAll(pathConfig.Uri, ".", "-") + ".jsonBody"
		}
		generateParameterDefinitions(swaggerInfo, pathConfig.Uri, parentPath, itemParamInput.Name, itemParamInput)
		if _, exist := hasDealTable[realParamName]; !exist {
			hasDealTable[realParamName] = true
			generateParam := &define.SwaggerPathConfigParameter{
				Type:        wrapper.TernaryOperator.String(realParamName == "jsonBody", "", wrapper.String(itemParamInput.Type)).Value(),
				Description: wrapper.TernaryOperator.String(realParamName == "jsonBody", "参数结构", wrapper.String(itemParamInput.Description)).Value(),
				Name:        realParamName,
				In:          itemParamInput.In,
				Required:    itemParamInput.Required,
				Schema: &define.SwaggerPathConfigParameterSchema{
					Ref: "",
				},
			}
			if len(parentPath) > 0 {
				generateParam.Schema.Ref = getRefValue(pathConfig.Uri + ".jsonBody")
				generateParam.Type = ""
			}
			swaggerInfo.Paths[pathConfig.Uri][pathConfig.Method].Parameters = append(swaggerInfo.Paths[pathConfig.Uri][pathConfig.Method].Parameters, generateParam)
		}
	}

}

// generatePathResponseConfig 生成响应配置
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:43 2024/4/25
func generatePathResponseConfig(swaggerInfo *define.Swagger, pathConfig *define.SwaggerPathInput) {
	hasDealResponseTable := map[string]bool{}
	for _, itemResponseConfig := range pathConfig.ResponseList {
		for _, itemResponseInput := range itemResponseConfig.List {
			if len(itemResponseInput.Field) == 0 {
				// 未指定参数名, 忽略
				continue
			}
			// name 可能是 x.x.x 递归数组, 或者 x.x.[].x
			outputDefine := strings.TrimLeft(strings.ReplaceAll(pathConfig.Uri, ".", "-"), "/") + "." + itemResponseConfig.Code + ".output"
			generateParameterDefinitions(swaggerInfo, pathConfig.Uri, outputDefine, itemResponseInput.Field, &define.SwaggerParameterInput{
				Type:        itemResponseInput.Type,
				Description: itemResponseInput.Description,
				Name:        itemResponseInput.Field,
				In:          consts.RequestDataLocationBody.String(),
				Required:    false,
				EnumList:    nil,
			})
			namePath := strings.Split(itemResponseInput.Field, ".")
			if _, exist := hasDealResponseTable[namePath[0]]; !exist {
				hasDealResponseTable[namePath[0]] = true
				swaggerInfo.Paths[pathConfig.Uri][pathConfig.Method].Responses[itemResponseConfig.Code] = &define.SwaggerPathConfigResponse{
					Description: "返回数据",
					Schema: &define.SwaggerPathConfigResponseSchema{
						Ref: getRefValue(outputDefine),
					},
				}
			}
		}
	}
}

// generateParameterDefinitions 生成请求参数的描述
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:06 2024/4/22
func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, parentPath string, subPath string, paramConfig *define.SwaggerParameterInput) {
	setGlobalMapDefinition(swaggerInfo, paramConfig.Type)
	uri = strings.ReplaceAll(strings.TrimLeft(uri, "/"), ".", "-")
	parentPath = strings.TrimLeft(parentPath, "/")
	checkPath := getCheckPath(parentPath)
	subPathArr := strings.Split(subPath, ".")
	initAnyDefinition(swaggerInfo, checkPath)

	if len(subPathArr) == 1 {
		handleOneLevelSubPath(swaggerInfo, uri, parentPath, subPath, paramConfig)
		return
	}
	if len(parentPath) == 0 {
		parentPath = uri + ".input"
	}
	if len(subPathArr) == 2 {
		if subPathArr[0] != "[]" {
			initAnyDefinition(swaggerInfo, parentPath)
		}
		if subPathArr[1] == "[]" {
			swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
				Description: paramConfig.Description,
				Type:        consts.SwaggerDataTypeArray,
				Items: &define.SwaggerDefinitionPropertyItem{
					Type: util.GetSwaggerType(paramConfig.Type),
					Ref:  "",
					Enum: nil,
				},
			}
		} else {
			if subPathArr[0] == "[]" {
				generateParameterDefinitions(swaggerInfo, uri, parentPath+".item", subPathArr[1], paramConfig)
				return
			} else {
				swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
					Description: "参数描述",
					Type:        consts.SwaggerDataTypeObject,
					AllOf: []map[string]string{
						{
							consts.SwaggerRefKey: getRefValue(parentPath + "." + subPathArr[0]),
						},
					},
				}
			}
			storageSubPath := parentPath + "." + subPathArr[0]
			if subPathArr[1] == "[]" {
				storageSubPath += ".item"
			}
			initAnyDefinition(swaggerInfo, storageSubPath)
			swaggerInfo.Definitions[storageSubPath].Type = wrapper.TernaryOperator.String(strings.HasSuffix(parentPath, "[]"), "array", consts.SwaggerDataTypeObject).Value()
			// 设置字段必传
			addRequiredField(swaggerInfo, storageSubPath, subPathArr[1], paramConfig.Required)
			swaggerInfo.Definitions[storageSubPath].Properties[subPathArr[1]] = &define.SwaggerDefinitionProperty{
				Description: paramConfig.Description,
				Type:        util.GetSwaggerType(paramConfig.Type),
			}
		}
		return
	}

	if _, exist := swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]]; !exist {
		if subPathArr[1] == "[]" {
			nextParentPath := parentPath + "." + subPathArr[0] + ".item"
			swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
				Description: "参数描述",
				Type:        consts.SwaggerDataTypeArray,
				Items: &define.SwaggerDefinitionPropertyItem{
					Type: "",
					Ref:  getRefValue(nextParentPath),
					Enum: nil,
				},
			}
			generateParameterDefinitions(swaggerInfo, uri, nextParentPath, strings.Join(subPathArr[2:], "."), paramConfig)
			return
		}
		itemSwaggerDefinition := &define.SwaggerDefinitionProperty{
			Description: "对象描述",
			Type:        wrapper.TernaryOperator.String(subPathArr[1] == "[]", "array", consts.SwaggerDataTypeObject).Value(),
			Items:       nil,
			AllOf:       nil,
		}
		if itemSwaggerDefinition.Type == consts.SwaggerDataTypeObject {
			itemSwaggerDefinition.AllOf = []map[string]string{map[string]string{
				consts.SwaggerRefKey: getRefValue(parentPath + "." + subPathArr[0]),
			}}
		} else if itemSwaggerDefinition.Type == consts.SwaggerDataTypeArray {
			itemSwaggerDefinition.Description = "数组描述"
			itemSwaggerDefinition.Items = &define.SwaggerDefinitionPropertyItem{
				Type: "",
				Ref:  getRefValue(parentPath + "." + subPathArr[0] + ".item"),
				Enum: nil,
			}
		}
		swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = itemSwaggerDefinition
	}
	generateParameterDefinitions(swaggerInfo, uri, parentPath+"."+subPathArr[0], strings.Join(subPathArr[1:], "."), paramConfig)
}

// handleOneLevelSubPath 处理subPath一层的情况
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:50 2024/4/25
func handleOneLevelSubPath(swaggerInfo *define.Swagger, uri string, parentPath string, subPath string, paramConfig *define.SwaggerParameterInput) {
	if paramConfig.In != strings.ToLower(consts.RequestDataLocationBody.String()) && !isGenerateOutput(parentPath) {
		// 长度为1, 还不在 body, 无需生成结构体
		return
	}
	if strings.HasSuffix(paramConfig.Type, "[]") {
		swaggerInfo.Definitions[parentPath].Properties[subPath] = &define.SwaggerDefinitionProperty{
			Description: paramConfig.Description,
			Type:        consts.SwaggerDataTypeArray,
			Items: &define.SwaggerDefinitionPropertyItem{
				Type: util.GetSwaggerType(strings.TrimSuffix(paramConfig.Type, "[]")),
				Ref:  "",
				Enum: nil,
			},
		}
		return
	}
	if isGlobalMapType(paramConfig.Type) {
		swaggerInfo.Definitions[parentPath].Properties[subPath] = &define.SwaggerDefinitionProperty{
			Description: paramConfig.Description,
			Type:        consts.SwaggerDataTypeObject,
			AllOf: []map[string]string{
				{
					consts.SwaggerRefKey: getRefValue(consts.SwaggerBaseObjectDefinitionName),
				},
			},
		}
		return
	}
	initAnyDefinition(swaggerInfo, parentPath)
	if paramConfig.Required {
		swaggerInfo.Definitions[parentPath].Required = append(swaggerInfo.Definitions[parentPath].Required, subPath)
	}
	swaggerInfo.Definitions[parentPath].Properties[subPath] = &define.SwaggerDefinitionProperty{
		Description: paramConfig.Description,
		Type:        util.GetSwaggerType(paramConfig.Type),
	}
}

func getUri(uri string) string {
	return "/" + strings.TrimLeft(uri, "/")
}

// setGlobalMapDefinition ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 15:38 2024/4/25
func setGlobalMapDefinition(swaggerInfo *define.Swagger, dataType string) {
	if !isGlobalMapType(dataType) {
		return
	}
	// 只要最终类型存在mao， 就一定会用到 consts.SwaggerBaseObjectDefinitionName
	if nil == swaggerInfo.Definitions {
		swaggerInfo.Definitions = map[string]*define.SwaggerDefinition{}
	}
	if _, exist := swaggerInfo.Definitions[consts.SwaggerBaseObjectDefinitionName]; exist {
		return
	}
	swaggerInfo.Definitions[consts.SwaggerBaseObjectDefinitionName] = &define.SwaggerDefinition{
		Type:       consts.SwaggerDataTypeObject,
		Required:   make([]string, 0),
		Properties: make(map[string]*define.SwaggerDefinitionProperty),
	}
}

// isGlobalMapType ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 15:46 2024/4/25
func isGlobalMapType(dataType string) bool {
	return wrapper.ArrayType([]string{
		consts.DataTypeMapAnyAny.String(),
		consts.DataTypeMapStrUint.String(),
		consts.DataTypeMapStrInt.String(),
		consts.DataTypeMapStrSlice.String(),
		consts.DataTypeMapStrFloat.String(),
		consts.DataTypeMapStrBool.String(),
		consts.DataTypeMapStrAny.String(),
	}).Has(dataType) >= 0
}

// initAnyDefinition 初始化一个definition
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:21 2024/4/25
func initAnyDefinition(swaggerInfo *define.Swagger, definitionName string) {
	if len(definitionName) == 0 {
		return
	}
	if nil == swaggerInfo.Definitions {
		swaggerInfo.Definitions = map[string]*define.SwaggerDefinition{}
	}
	if _, exist := swaggerInfo.Definitions[definitionName]; exist {
		return
	}
	swaggerInfo.Definitions[definitionName] = &define.SwaggerDefinition{
		Type:       consts.SwaggerDataTypeObject,
		Format:     consts.DataTypeMapStrAny.String(),
		Required:   make([]string, 0),
		Properties: make(map[string]*define.SwaggerDefinitionProperty),
	}
}

// getRefValue 获取refValue
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:31 2024/4/25
func getRefValue(path string) string {
	return consts.SwaggerRefValPrefix + strings.TrimLeft(path, "/")
}

// addRequiredField 添加必传字段
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:57 2024/4/25
func addRequiredField(swaggerInfo *define.Swagger, definitionName string, field string, isRequired bool) {
	if !isRequired {
		return
	}
	swaggerInfo.Definitions[definitionName].Required = append(swaggerInfo.Definitions[definitionName].Required, definitionName)
}

// getCheckPath 获取检查的Definition
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:01 2024/4/25
func getCheckPath(parentPath string) string {
	parentPathArr := strings.Split(parentPath, ".")
	if isGenerateOutput(parentPath) {
		return strings.Join([]string{parentPathArr[0], parentPathArr[1], parentPathArr[2]}, ".")
	} else {
		if len(parentPathArr) >= 2 {
			return strings.Join([]string{parentPathArr[0], parentPathArr[1]}, ".")
		}
	}
	return parentPath
}

// isGenerateOutput ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:52 2024/4/25
func isGenerateOutput(parentPath string) bool {
	parentPathArr := strings.Split(parentPath, ".")
	if len(parentPathArr) >= 3 && parentPathArr[2] == "output" {
		return true
	}
	return false
}