优化一波api-doc代码

2024-04-25 17:06:33 +08:00 · 2024-04-25 17:06:33 +08:00 · e03e1b9370
commit e03e1b9370
parent fb906a49ea
3 changed files with 75 additions and 44 deletions
--- a/go.mod
+++ b/go.mod
@ -3,7 +3,7 @@ module git.zhangdeman.cn/gateway/api-doc
 go 1.22.2

 require (
-	git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425083843-f40760f6ee22
+	git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425085343-09fdf2f01e4f
 	git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240422034417-8c922be06d95
 )

--- a/go.sum
+++ b/go.sum
@ -4,6 +4,8 @@ git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad h1:hOmxPR
 git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k=
 git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425083843-f40760f6ee22 h1:98cFHVl4z4+AboA3r6UOVYKDOLgANePFjnItZ3FufvY=
 git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425083843-f40760f6ee22/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k=
+git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425085343-09fdf2f01e4f h1:bbn19GoW7ScVB6BybUthRqsc4hxc0EqmGyCICXlXkr8=
+git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425085343-09fdf2f01e4f/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k=
 git.zhangdeman.cn/zhangdeman/easymap v0.0.0-20240311030808-e2a2e6a3c211 h1:I/wOsRpCSRkU9vo1u703slQsmK0wnNeZzsWQOGtIAG0=
 git.zhangdeman.cn/zhangdeman/easymap v0.0.0-20240311030808-e2a2e6a3c211/go.mod h1:SrtvrQRdzt+8KfYzvosH++gWxo2ShPTzR1m3VQ6uX7U=
 git.zhangdeman.cn/zhangdeman/serialize v0.0.0-20240325080031-1f58204e8687 h1:uQcGqdzi4UdpZlp4f4FUPeBqoygP58pEKJkmN3ROsE0=
--- a/swagger/run.go
+++ b/swagger/run.go
@ -201,38 +201,15 @@ func generatePathResponseConfig(swaggerInfo *define.Swagger, pathConfig *define.
 //
 // Date : 14:06 2024/4/22
 func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, parentPath string, subPath string, paramConfig *define.SwaggerParameterInput) {
-	if isGlobalMapType(paramConfig.Type) {
-		// 只要最终类型存在mao， 就一定会用到 global_map
-		setGlobalMapDefinition(swaggerInfo)
-	}
+	setGlobalMapDefinition(swaggerInfo, paramConfig.Type)
 	uri = strings.TrimLeft(uri, "/")
 	parentPath = strings.TrimLeft(parentPath, "/")
-	if nil == swaggerInfo.Definitions {
-		swaggerInfo.Definitions = map[string]*define.SwaggerDefinition{}
-	}
-	parentPathArr := strings.Split(parentPath, ".")
-	checkPath := parentPath
-	if len(parentPathArr) >= 2 {
-		checkPath = strings.Join([]string{parentPathArr[0], parentPathArr[1]}, ".")
-	}
+	checkPath := getCheckPath(parentPath)
 	subPathArr := strings.Split(subPath, ".")
-	if _, exist := swaggerInfo.Definitions[checkPath]; !exist && len(parentPath) > 0 {
-		initAnyDefinition(swaggerInfo, checkPath)
-	}
+	initAnyDefinition(swaggerInfo, checkPath)

 	if len(subPathArr) == 1 {
-		if paramConfig.In != strings.ToLower(consts.RequestLocationBody) {
-			// 长度为1, 还不在 body, 无需生成结构体
-			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),
-		}
+		handleOneLevelSubPath(swaggerInfo, uri, parentPath, subPath, paramConfig)
 		return
 	}
 	if len(parentPath) == 0 {
@ -245,9 +222,9 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 		if subPathArr[1] == "[]" {
 			swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
 				Description: paramConfig.Description,
-				Type:        "array",
+				Type:        consts.SwaggerDataTypeArray,
 				Items: map[string]string{
-					"type": util.GetSwaggerType(paramConfig.Type),
+					consts.SwaggerTypeKey: util.GetSwaggerType(paramConfig.Type),
 				},
 			}
 		} else {
@ -258,9 +235,11 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 				swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
 					Description: "参数描述",
 					Type:        consts.SwaggerDataTypeObject,
-					AllOf: []map[string]string{map[string]string{
-						"$ref": getRefValue(parentPath + "." + subPathArr[0]),
-					}},
+					AllOf: []map[string]string{
+						{
+							consts.SwaggerRefKey: getRefValue(parentPath + "." + subPathArr[0]),
+						},
+					},
 				}
 			}
 			storageSubPath := parentPath + "." + subPathArr[0]
@ -269,9 +248,8 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 			}
 			initAnyDefinition(swaggerInfo, storageSubPath)
 			swaggerInfo.Definitions[storageSubPath].Type = wrapper.TernaryOperator.String(strings.HasSuffix(parentPath, "[]"), "array", consts.SwaggerDataTypeObject).Value()
-			if paramConfig.Required {
-				swaggerInfo.Definitions[storageSubPath].Required = append(swaggerInfo.Definitions[storageSubPath].Required, subPathArr[1])
-			}
+			// 设置字段必传
+			addRequiredField(swaggerInfo, storageSubPath, subPathArr[1], paramConfig.Required)
 			swaggerInfo.Definitions[storageSubPath].Properties[subPathArr[1]] = &define.SwaggerDefinitionProperty{
 				Description: paramConfig.Description,
 				Type:        util.GetSwaggerType(paramConfig.Type),
@ -285,9 +263,9 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 			nextParentPath := parentPath + "." + subPathArr[0] + ".item"
 			swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
 				Description: "参数描述",
-				Type:        "array",
+				Type:        consts.SwaggerDataTypeArray,
 				Items: map[string]string{
-					"$ref": getRefValue(nextParentPath),
+					consts.SwaggerRefKey: getRefValue(nextParentPath),
 				},
 			}
 			generateParameterDefinitions(swaggerInfo, uri, nextParentPath, strings.Join(subPathArr[2:], "."), paramConfig)
@ -301,20 +279,39 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 		}
 		if itemSwaggerDefinition.Type == consts.SwaggerDataTypeObject {
 			itemSwaggerDefinition.AllOf = []map[string]string{map[string]string{
-				"$ref": getRefValue(parentPath + "." + subPathArr[0]),
+				consts.SwaggerRefKey: getRefValue(parentPath + "." + subPathArr[0]),
 			}}
-		} else if itemSwaggerDefinition.Type == "array" {
+		} else if itemSwaggerDefinition.Type == consts.SwaggerDataTypeArray {
 			itemSwaggerDefinition.Description = "数组描述"
 			itemSwaggerDefinition.Items = map[string]string{
-				"$ref": getRefValue(parentPath + "." + subPathArr[0] + ".item"),
+				consts.SwaggerRefKey: getRefValue(parentPath + "." + subPathArr[0] + ".item"),
 			}
 		}
 		swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = itemSwaggerDefinition
 	}
-	// fmt.Println(parentPath + "." + subPathArr[0])
 	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.RequestLocationBody) {
+		// 长度为1, 还不在 body, 无需生成结构体
+		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, "/")
 }
@ -324,7 +321,11 @@ func getUri(uri string) string {
 // Author : go_developer@163.com<白茶清欢>
 //
 // Date : 15:38 2024/4/25
-func setGlobalMapDefinition(swaggerInfo *define.Swagger) {
+func setGlobalMapDefinition(swaggerInfo *define.Swagger, dataType string) {
+	if !isGlobalMapType(dataType) {
+		return
+	}
+	// 只要最终类型存在mao， 就一定会用到 global_map
 	if nil == swaggerInfo.Definitions {
 		swaggerInfo.Definitions = map[string]*define.SwaggerDefinition{}
 	}
@ -333,7 +334,7 @@ func setGlobalMapDefinition(swaggerInfo *define.Swagger) {
 	}
 	swaggerInfo.Definitions["global_map"] = &define.SwaggerDefinition{
 		Type:       consts.SwaggerDataTypeObject,
-		Required:   nil,
+		Required:   make([]string, 0),
 		Properties: make(map[string]*define.SwaggerDefinitionProperty),
 	}
 }
@ -361,6 +362,9 @@ func isGlobalMapType(dataType string) bool {
 //
 // 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{}
 	}
@ -383,3 +387,28 @@ func initAnyDefinition(swaggerInfo *define.Swagger, definitionName string) {
 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 len(parentPathArr) >= 2 {
+		return strings.Join([]string{parentPathArr[0], parentPathArr[1]}, ".")
+	}
+	return parentPath
+}