优化一波api-doc代码

define/consts.go

@@ -1,23 +0,0 @@
-// Package define ...
-//
-// Description : define ...
-//
-// Author : go_developer@163.com<白茶清欢>
-//
-// Date : 2024-04-19 12:12
-package define
-
-const (
-	SwaggerVersion2 = "2.0"
-)
-
-const (
-	LicenseApache2 = "Apache 2.0" // apache
-)
-
-var (
-	// LicenseLinkTable 开源协议内容映射表
-	LicenseLinkTable = map[string]string{
-		LicenseApache2: "http://www.apache.org/licenses/LICENSE-2.0.html",
-	}
-)

define/types.go

@@ -87,6 +87,7 @@ type SwaggerPathConfigResponse struct {
 // Date : 17:01 2024/4/19
 type SwaggerDefinition struct {
 	Type       string                                `json:"type"`               // 类型
+	Format     string                                `json:"format,omitempty"`   // 原始数据类型
 	Required   []string                              `json:"required,omitempty"` // 必传参数列表
 	Properties map[string]*SwaggerDefinitionProperty `json:"properties"`         // 参数名 => 参数配置
 }

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-20240422030654-fc4470a2cebc
+	git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad
 	git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240422034417-8c922be06d95
 )
 

go.sum

@@ -1,5 +1,7 @@
 git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc h1:1fgPDwrLyvRP5A5PAoog3RtRQZ6c7JFtl+ZJmFEqyQQ=
 git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k=
+git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad h1:hOmxPRzrD6tDPjZH8lVBuSkz3WXr7j/q2aD9AvEGTFg=
+git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad/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=

swagger/run.go

@@ -25,7 +25,7 @@ func Generate(docConfig *define.SwaggerInput) (*define.Swagger, error) {
 	formatDocConfig(docConfig)
 	swaggerInfo := &define.Swagger{
 		Schemes:     docConfig.Schemes,
-		Swagger:     define.SwaggerVersion2,
+		Swagger:     consts.SwaggerDocVersion2,
 		Host:        docConfig.Host,
 		BasePath:    docConfig.BasePath,
 		Info:        docConfig.Info,
@@ -148,7 +148,7 @@ func generatePathParameterConfig(swaggerInfo *define.Swagger, pathConfig *define
 				Schema:      map[string]string{},
 			}
 			if len(parentPath) > 0 {
-				generateParam.Schema["$ref"] = "#/definitions/" + strings.TrimLeft(pathConfig.Uri, "/") + ".jsonBody"
+				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)
@@ -177,7 +177,7 @@ func generatePathParameterConfig(swaggerInfo *define.Swagger, pathConfig *define
 				swaggerInfo.Paths[pathConfig.Uri][pathConfig.Method].Responses[itemResponseConfig.Code] = &define.SwaggerPathConfigResponse{
 					Description: "返回数据",
 					Schema: map[string]string{
-						"$ref": "#/definitions/" + outputDefine,
+						"$ref": getRefValue(outputDefine),
 					},
 				}
 			}
@@ -191,6 +191,10 @@ func generatePathParameterConfig(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)
+	}
 	uri = strings.TrimLeft(uri, "/")
 	parentPath = strings.TrimLeft(parentPath, "/")
 	if nil == swaggerInfo.Definitions {
@@ -203,11 +207,7 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 	}
 	subPathArr := strings.Split(subPath, ".")
 	if _, exist := swaggerInfo.Definitions[checkPath]; !exist && len(parentPath) > 0 {
-		swaggerInfo.Definitions[checkPath] = &define.SwaggerDefinition{
+		initAnyDefinition(swaggerInfo, checkPath)
-			Type:       "object",
-			Required:   make([]string, 0),
-			Properties: make(map[string]*define.SwaggerDefinitionProperty),
-		}
 	}
 
 	if len(subPathArr) == 1 {
@@ -215,14 +215,7 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 			// 长度为1, 还不在 body, 无需生成结构体
 			return
 		}
-		if _, exist := swaggerInfo.Definitions[parentPath]; !exist {
+		initAnyDefinition(swaggerInfo, parentPath)
-			swaggerInfo.Definitions[parentPath] = &define.SwaggerDefinition{
-				Type:       "object",
-				Required:   make([]string, 0),
-				Properties: make(map[string]*define.SwaggerDefinitionProperty),
-			}
-		}
-		swaggerInfo.Definitions[parentPath].Type = "object"
 		if paramConfig.Required {
 			swaggerInfo.Definitions[parentPath].Required = append(swaggerInfo.Definitions[parentPath].Required, subPath)
 		}
@@ -237,11 +230,7 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 	}
 	if len(subPathArr) == 2 {
 		if _, exist := swaggerInfo.Definitions[parentPath]; !exist && subPathArr[0] != "[]" {
-			swaggerInfo.Definitions[parentPath] = &define.SwaggerDefinition{
+			initAnyDefinition(swaggerInfo, parentPath)
-				Type:       "object",
-				Required:   make([]string, 0),
-				Properties: make(map[string]*define.SwaggerDefinitionProperty),
-			}
 		}
 		if subPathArr[1] == "[]" {
 			swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
@@ -258,9 +247,9 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 			} else {
 				swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = &define.SwaggerDefinitionProperty{
 					Description: "参数描述",
-					Type:        "object",
+					Type:        consts.SwaggerDataTypeObject,
 					AllOf: []map[string]string{map[string]string{
-						"$ref": "#/definitions/" + parentPath + "." + subPathArr[0],
+						"$ref": getRefValue(parentPath + "." + subPathArr[0]),
 					}},
 				}
 			}
@@ -268,13 +257,8 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 			if subPathArr[1] == "[]" {
 				storageSubPath += ".item"
 			}
-			if _, exist := swaggerInfo.Definitions[storageSubPath]; !exist {
+			initAnyDefinition(swaggerInfo, storageSubPath)
-				swaggerInfo.Definitions[storageSubPath] = &define.SwaggerDefinition{
+			swaggerInfo.Definitions[storageSubPath].Type = wrapper.TernaryOperator.String(strings.HasSuffix(parentPath, "[]"), "array", consts.SwaggerDataTypeObject).Value()
-					Type:       wrapper.TernaryOperator.String(strings.HasSuffix(parentPath, "[]"), "array", "object").Value(),
-					Required:   make([]string, 0),
-					Properties: make(map[string]*define.SwaggerDefinitionProperty),
-				}
-			}
 			if paramConfig.Required {
 				swaggerInfo.Definitions[storageSubPath].Required = append(swaggerInfo.Definitions[storageSubPath].Required, subPathArr[1])
 			}
@@ -293,7 +277,7 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 				Description: "参数描述",
 				Type:        "array",
 				Items: map[string]string{
-					"$ref": "#/definitions/" + nextParentPath,
+					"$ref": getRefValue(nextParentPath),
 				},
 			}
 			generateParameterDefinitions(swaggerInfo, uri, nextParentPath, strings.Join(subPathArr[2:], "."), paramConfig)
@@ -301,18 +285,18 @@ func generateParameterDefinitions(swaggerInfo *define.Swagger, uri string, paren
 		}
 		itemSwaggerDefinition := &define.SwaggerDefinitionProperty{
 			Description: "对象描述",
-			Type:        wrapper.TernaryOperator.String(subPathArr[1] == "[]", "array", "object").Value(),
+			Type:        wrapper.TernaryOperator.String(subPathArr[1] == "[]", "array", consts.SwaggerDataTypeObject).Value(),
 			Items:       nil,
 			AllOf:       nil,
 		}
-		if itemSwaggerDefinition.Type == "object" {
+		if itemSwaggerDefinition.Type == consts.SwaggerDataTypeObject {
 			itemSwaggerDefinition.AllOf = []map[string]string{map[string]string{
-				"$ref": "#/definitions/" + parentPath + "." + subPathArr[0],
+				"$ref": getRefValue(parentPath + "." + subPathArr[0]),
 			}}
 		} else if itemSwaggerDefinition.Type == "array" {
 			itemSwaggerDefinition.Description = "数组描述"
 			itemSwaggerDefinition.Items = map[string]string{
-				"$ref": "#/definitions/" + parentPath + "." + subPathArr[0] + ".item",
+				"$ref": getRefValue(parentPath + "." + subPathArr[0] + ".item"),
 			}
 		}
 		swaggerInfo.Definitions[parentPath].Properties[subPathArr[0]] = itemSwaggerDefinition
@@ -338,7 +322,7 @@ func setGlobalMapDefinition(swaggerInfo *define.Swagger) {
 		return
 	}
 	swaggerInfo.Definitions["global_map"] = &define.SwaggerDefinition{
-		Type:       "object",
+		Type:       consts.SwaggerDataTypeObject,
 		Required:   nil,
 		Properties: make(map[string]*define.SwaggerDefinitionProperty),
 	}
@@ -349,11 +333,7 @@ func setGlobalMapDefinition(swaggerInfo *define.Swagger) {
 // Author : go_developer@163.com<白茶清欢>
 //
 // Date : 15:46 2024/4/25
-func isGlobalMapType(path string, dataType string) bool {
+func isGlobalMapType(dataType string) bool {
-	pathArr := strings.Split(path, ".")
-	if len(pathArr) > 2 {
-		return false
-	}
 	return wrapper.ArrayType([]string{
 		consts.DataTypeMapAnyAny,
 		consts.DataTypeMapStrUint,
@@ -364,3 +344,32 @@ func isGlobalMapType(path string, dataType string) bool {
 		consts.DataTypeMapStrAny,
 	}).Has(dataType) >= 0
 }
+
+// initAnyDefinition 初始化一个definition
+//
+// Author : go_developer@163.com<白茶清欢>
+//
+// Date : 16:21 2024/4/25
+func initAnyDefinition(swaggerInfo *define.Swagger, definitionName string) {
+	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:     "",
+		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 "#/definitions/" + strings.TrimLeft(path, "/")
+}

swagger/run_test.go

@@ -19,7 +19,7 @@ import (
 func TestGenerate(t *testing.T) {
 	res, _ := Generate(&define.SwaggerInput{
 		Schemes:  []string{},
-		Swagger:  define.SwaggerVersion2,
+		Swagger:  consts.SwaggerDocVersion2,
 		Host:     "http://www.baidu.com",
 		BasePath: "/",
 		Info: define.Info{