feat: 增加公共的路由res的定义

goodluckxu-go · Feb 19, 2024 · 52c1e3e · 52c1e3e
1 parent 17b7973
commit 52c1e3e
Show file tree

Hide file tree

Showing 7 changed files with 96 additions and 31 deletions.
diff --git a/README.md b/README.md
@@ -45,6 +45,12 @@ go install github.com/goodluckxu-go/openapi/cmd/apigen@latest
 package main
 ~~~
 
+#### docs.go 文档中定义公共的 route.go 中的属性，和 route.go 的注释一致，在@后面添加global.
+~~~go
+// @global.res: status=500; in=application/json; content=服务器链接失败; desc=系统内部错误
+package main
+~~~
+
 ### route.go文档注释说明
 - @开始的标题，用 ; 分割，分割成对象。每个对象用 = 分割，分割成键，值，如果不存在 = 好则表示值是字符串 true
 

diff --git a/examples/doc.go b/examples/doc.go
@@ -28,7 +28,7 @@
 // @tags: name=admin;description=后台管理
 //
 // 验证设置
-// @components.securitySchemes: field=token;type=apiKey;name=api_key;in=header
+// @components.securitySchemes: field=token;type=apiKey;name=token;in=header
 //
 // @components.securitySchemes: |-
 //
@@ -42,4 +42,6 @@
 //		     }
 //		   }
 //		 }
+//
+// @global.res: status=500; in=application/json; content=服务器链接失败; desc=系统内部错误
 package examples
diff --git a/examples/docs/openapi.json b/examples/docs/openapi.json
diff --git a/examples/docs/openapi.yaml b/examples/docs/openapi.yaml
@@ -136,7 +136,7 @@ components:
                     type: string
                 deprecated:
                     format: bool
-                    type: string
+                    type: boolean
                 description:
                     format: string
                     type: string
@@ -363,23 +363,12 @@ components:
                 id:
                     description: 主键
                     format: int
-                    type: string
+                    type: integer
                 name:
                     description: 名称
                     format: string
                     type: string
             type: object
-        github.jparrowsec.cn.goodluckxu-go.openapi.examples.Test:
-            description: |
-                Test 测试结构体注释
-            properties:
-                map:
-                    description: 对象
-                    properties:
-                        string:
-                            $ref: '#/components/schemas/github.jparrowsec.cn.goodluckxu-go.openapi.examples.ExampleRes'
-                    type: object
-            type: object
     securitySchemes:
         projectID:
             flows:
@@ -391,7 +380,7 @@ components:
             type: oauth2
         token:
             in: header
-            name: api_key
+            name: token
             type: apiKey
 externalDocs:
     description: Find out more about Swagger
@@ -445,9 +434,18 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/github.jparrowsec.cn.goodluckxu-go.openapi.examples.ExampleRes'
                     description: 错误信息
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                default: 服务器链接失败
+                                type: string
+                    description: 系统内部错误
             security:
                 - token: []
-                - projectID: []
+                - projectID:
+                    - write:pets
+                    - read:pets
             summary: 用户信息
             tags:
                 - admin
@@ -473,9 +471,18 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/github.jparrowsec.cn.goodluckxu-go.openapi.examples.ExampleRes'
                     description: 错误信息
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                default: 服务器链接失败
+                                type: string
+                    description: 系统内部错误
             security:
                 - token: []
-                - projectID: []
+                - projectID:
+                    - write:pets
+                    - read:pets
             summary: 登录后台
             tags:
                 - admin
@@ -495,9 +502,18 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/github.jparrowsec.cn.goodluckxu-go.openapi.examples.ExampleRes'
                     description: 错误信息
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                default: 服务器链接失败
+                                type: string
+                    description: 系统内部错误
             security:
                 - token: []
-                - projectID: []
+                - projectID:
+                    - write:pets
+                    - read:pets
             summary: 退出登录
             tags:
                 - admin
@@ -534,11 +550,14 @@ paths:
                     content:
                         application/json:
                             schema:
-                                $ref: '#/components/schemas/github.jparrowsec.cn.goodluckxu-go.openapi.examples.Test'
-                    description: 错误信息
+                                default: 服务器链接失败
+                                type: string
+                    description: 系统内部错误
             security:
                 - token: []
-                - projectID: []
+                - projectID:
+                    - write:pets
+                    - read:pets
             summary: 获取用户列表
             tags:
                 - admin

diff --git a/examples/route.go b/examples/route.go
@@ -16,6 +16,12 @@ type Test struct {
 	Map map[string]ExampleRes `json:"map"` // 对象
 }
 
+// ServerError 是服务器错误信息
+type ServerError struct {
+	Code int    `json:"code" default:"500"`   // 错误码
+	Msg  string `json:"msg" default:"系统内部错误"` // 错误信息
+}
+
 // GetList openapi
 // @summary: 获取用户列表
 // @description: 用户列表接口需要授权
@@ -24,8 +30,7 @@ type Test struct {
 // @param: in=query; name=sex; type=string; desc=用户性别
 // @res: status=200; in=application/json; content=[]examples.ExampleRes; desc=返回信息
 // @res: status=404; in=application/json; content=github.com/getkin/kin-openapi/openapi3.T; desc=错误信息
-// @res: status=500; in=application/json; content=examples.Test; desc=错误信息
-// @security: token;projectID
+// @security: token;projectID=write:pets,read:pets
 // @router: method=get;path=/user/list
 func GetList() {
 
@@ -38,7 +43,7 @@ func GetList() {
 // @body: in=application/json; content=examples.ExampleBody; desc=用户信息
 // @res: status=200; in=application/json; content=examples.ExampleRes; desc=返回信息
 // @res: status=404; in=application/json; content=examples.ExampleRes; desc=错误信息
-// @security: token;projectID
+// @security: token;projectID=write:pets,read:pets
 // @router: method=post;path=/admin/login
 func Login() {
 
@@ -50,7 +55,7 @@ func Login() {
 // @tags: admin
 // @res: status=200; in=application/json; content=examples.ExampleRes; desc=返回信息
 // @res: status=404; in=application/json; content=examples.ExampleRes; desc=错误信息
-// @security: token;projectID
+// @security: token;projectID=write:pets,read:pets
 // @router: method=delete;path=/admin/logout
 func Logout() {
 
@@ -63,7 +68,7 @@ func Logout() {
 // @param: in=path; name=id; type=integer(int64); required; desc=主键; minimum=1;maximum=10;default=8
 // @res: status=200; in=application/json; content=examples.ExampleRes; desc=返回信息
 // @res: status=404; in=application/json; content=examples.ExampleRes; desc=错误信息
-// @security: token;projectID
+// @security: token;projectID=write:pets,read:pets
 // @router: method=get;path=/admin/{id}
 func Info() {
 

diff --git a/openapi_handle.go b/openapi_handle.go
@@ -15,6 +15,7 @@ type openapiHandle struct {
 	schemas       openapi3.Schemas
 	importStructs map[string]bool
 	sameStructs   map[string]string
+	globalRoutes  map[string]interface{}
 }
 
 func (o *openapiHandle) load(routeDir, docPath string) {
@@ -25,6 +26,7 @@ func (o *openapiHandle) load(routeDir, docPath string) {
 	o.schemas = map[string]*openapi3.SchemaRef{}
 	o.importStructs = map[string]bool{}
 	o.sameStructs = map[string]string{}
+	o.globalRoutes = map[string]interface{}{}
 	o.generateDoc(docPath)
 	o.generateRoute(routeDir)
 }
@@ -161,7 +163,7 @@ func (o *openapiHandle) generateRoute(routeDir string) {
 	if o.t.Paths == nil {
 		o.t.Paths = &openapi3.Paths{}
 	}
-	for k, v := range routes {
+	for k, vMap := range routes {
 		vList := strings.Split(k, "_")
 		path := strings.Join(vList[:len(vList)-1], "_")
 		method := vList[len(vList)-1]
@@ -204,7 +206,24 @@ func (o *openapiHandle) generateRoute(routeDir string) {
 				operation = pathItem.Trace
 			}
 		}
-		o.setOpenAPIByRoute(operation, v)
+		// 处理通用路由
+		for k1, v1 := range o.globalRoutes {
+			if vMap[k1] != nil {
+				switch setData := vMap[k1].(type) {
+				case []map[string]interface{}:
+					v1List, _ := v1.([]map[string]interface{})
+					setData = append(setData, v1List...)
+					vMap[k1] = setData
+				case map[string]interface{}:
+					v1Map, _ := v1.(map[string]interface{})
+					for k2, v2 := range v1Map {
+						setData[k2] = v2
+					}
+					vMap[k1] = setData
+				}
+			}
+		}
+		o.setOpenAPIByRoute(operation, vMap)
 		switch method {
 		case "get":
 			pathItem.Get = operation
@@ -478,8 +497,14 @@ func (o *openapiHandle) setType(schemeRef *openapi3.SchemaRef, types string, lev
 	}
 	strInfo := o.structs[types]
 	if strInfo == nil {
-		schemeRef.Value.Type = "string"
-		schemeRef.Value.Format = types
+		schemeRef.Value.Type = o.getType(types)
+		if level == 1 && schemeRef.Value.Type == "string" {
+			// 如果设置的类型是字符串则赋默认值
+			schemeRef.Value.Default = types
+		} else {
+			// 否则赋格式化
+			schemeRef.Value.Format = types
+		}
 	} else {
 		schemeRef.Ref = o.setScheme(strInfo, level)
 	}
@@ -574,6 +599,8 @@ func (o *openapiHandle) generateDoc(docPath string) {
 		log.Fatal(err)
 	}
 	o.setOpenAPIByDoc(o.t, asts.docs)
+	// 处理通用路由
+	o.globalRoutes["@res"] = asts.docs["@global.res"]
 }
 
 func (o *openapiHandle) setOpenAPIByDoc(dist any, dataMap map[string]interface{}) {

diff --git a/valid.go b/valid.go
@@ -41,6 +41,12 @@ var (
 		"@components.securitySchemes._.name":         {valType: validTypeString},
 		"@components.securitySchemes._.in":           {valType: validTypeString, valEnum: []string{"query", "header", "cookie"}},
 		"@components.securitySchemes._.flows":        {valType: validTypeJson},
+		// global
+		"@global.res":           {valType: validTypeMapArray, cutListSign: secondListCutSign, cutKeyValSign: secondKeyValueCutSign},
+		"@global.res._.status":  {valType: validTypeInteger},
+		"@global.res._.in":      {valType: validTypeString, valEnum: []string{"application/json", "application/xml"}},
+		"@global.res._.content": {valType: validTypeString},
+		"@global.res._.desc":    {valType: validTypeString},
 	}
 
 	validRoutesMap = map[string]*validStruct{