From 181f96368889debd93c1440773d6a0380919f55c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Thu, 25 Apr 2024 16:34:22 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E4=B8=80=E6=B3=A2api-doc?= =?UTF-8?q?=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/consts.go | 23 ------------ define/types.go | 1 + go.mod | 2 +- go.sum | 2 + swagger/run.go | 91 +++++++++++++++++++++++++-------------------- swagger/run_test.go | 2 +- 6 files changed, 55 insertions(+), 66 deletions(-) delete mode 100644 define/consts.go diff --git a/define/consts.go b/define/consts.go deleted file mode 100644 index 1e9a693..0000000 --- a/define/consts.go +++ /dev/null @@ -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", - } -) diff --git a/define/types.go b/define/types.go index ef323e5..a4eb807 100644 --- a/define/types.go +++ b/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"` // 参数名 => 参数配置 } diff --git a/go.mod b/go.mod index 0364660..93b0108 100644 --- 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-20240422030654-fc4470a2cebc + git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240422034417-8c922be06d95 ) diff --git a/go.sum b/go.sum index 11cc5d9..b8755e6 100644 --- a/go.sum +++ b/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= diff --git a/swagger/run.go b/swagger/run.go index 8a3a01b..87ac4e4 100644 --- a/swagger/run.go +++ b/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{ - Type: "object", - Required: make([]string, 0), - Properties: make(map[string]*define.SwaggerDefinitionProperty), - } + initAnyDefinition(swaggerInfo, checkPath) } 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 { - swaggerInfo.Definitions[parentPath] = &define.SwaggerDefinition{ - Type: "object", - Required: make([]string, 0), - Properties: make(map[string]*define.SwaggerDefinitionProperty), - } - } - swaggerInfo.Definitions[parentPath].Type = "object" + initAnyDefinition(swaggerInfo, parentPath) 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{ - Type: "object", - Required: make([]string, 0), - Properties: make(map[string]*define.SwaggerDefinitionProperty), - } + initAnyDefinition(swaggerInfo, parentPath) } 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 { - swaggerInfo.Definitions[storageSubPath] = &define.SwaggerDefinition{ - Type: wrapper.TernaryOperator.String(strings.HasSuffix(parentPath, "[]"), "array", "object").Value(), - Required: make([]string, 0), - Properties: make(map[string]*define.SwaggerDefinitionProperty), - } - } + 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]) } @@ -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 { - pathArr := strings.Split(path, ".") - if len(pathArr) > 2 { - return false - } +func isGlobalMapType(dataType string) bool { 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, "/") +} diff --git a/swagger/run_test.go b/swagger/run_test.go index 730d3a3..4b3e43d 100644 --- a/swagger/run_test.go +++ b/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{