feat: request and response nested struct

.vscode/launch.json

@@ -12,7 +12,7 @@
             "program": "${workspaceFolder}/cmd/apidoc/main.go",
             "args": [
                 "--dir", "../../examples/svc-user/",
-                "--output", "../../examples/docs"
+                "--output", "../../examples/docs",
             ]
         }
     ]

examples/docs/README.md

@@ -4,36 +4,38 @@
 
 1. [账户相关](./apis-account.md)
 
-    - [用户注册接口](./apis-account.md#1-用户注册接口)
+    1.1. [用户注册接口](./apis-account.md#1-用户注册接口)
 
-    - [用户登录接口](./apis-account.md#2-用户登录接口)
+    1.2. [用户登录接口](./apis-account.md#2-用户登录接口)
 
 2. [地址管理](./apis-address.md)
 
-    - [添加地址接口](./apis-address.md#1-添加地址接口)
+    2.1. [添加地址接口](./apis-address.md#1-添加地址接口)
 
-    - [更新地址接口](./apis-address.md#2-更新地址接口)
+    2.2. [更新地址接口](./apis-address.md#2-更新地址接口)
 
-    - [删除地址接口](./apis-address.md#3-删除地址接口)
+    2.3. [删除地址接口](./apis-address.md#3-删除地址接口)
 
-    - [获取地址信息](./apis-address.md#4-获取地址信息)
+    2.4. [获取地址信息](./apis-address.md#4-获取地址信息)
 
-    - [获取地址列表](./apis-address.md#5-获取地址列表)(Deprecated)
+    2.5. [获取地址列表](./apis-address.md#5-获取地址列表)(Deprecated)
 
 3. [资料管理](./apis-profile.md)
 
-    - [获取用户资料](./apis-profile.md#1-获取用户资料)
+    3.1. [获取用户资料](./apis-profile.md#1-获取用户资料)
 
 4. [菜单管理](./apis-menu.md)
 
-    - [获取菜单节点](./apis-menu.md#1-获取菜单节点)
+    4.1. [获取菜单节点](./apis-menu.md#1-获取菜单节点)
 
 5. [测试示例](./apis-demo.md)
 
-    - [struct数组](./apis-demo.md#1-struct数组)
+    5.1. [struct数组](./apis-demo.md#1-struct数组)
 
-    - [int数组](./apis-demo.md#2-int数组)
+    5.2. [struct嵌套](./apis-demo.md#2-struct嵌套)
 
-    - [int](./apis-demo.md#3-int)
+    5.3. [int数组](./apis-demo.md#3-int数组)
 
-    - [DemoMap](./apis-demo.md#4-DemoMap)
+    5.4. [int](./apis-demo.md#4-int)
+
+    5.5. [DemoMap](./apis-demo.md#5-DemoMap)

examples/docs/apis-demo.md

@@ -3,9 +3,10 @@
 其它一些示例演示
 
 1. [struct数组](#1-struct数组)
-2. [int数组](#2-int数组)
-3. [int](#3-int)
-4. [DemoMap](#4-DemoMap)
+2. [struct嵌套](#2-struct嵌套)
+3. [int数组](#3-int数组)
+4. [int](#4-int)
+5. [DemoMap](#5-DemoMap)
 
 ## apis
 
@@ -22,6 +23,9 @@ __Response__:
 [  //array[handler.DemoData]
   {  //object(handler.DemoData)
     "count": 123,  //int
+    "DemoObject": {  //object(handler.DemoObject)
+      "name": "abc"  //string
+    },
     "description": "abc",  //string
     "float_array": [  //array[float64]
       1.23
@@ -33,20 +37,32 @@ __Response__:
     "map": {  //object(Map)
       "abc": 123  //int
     },
-    "object_1": {  //object(handler.DemoObject)
-      "name": "abc"  //string
-    },
-    "object_2": {  //object(handler.DemoObject)
-      "name": "abc"  //string
-    },
     "title": "abc"  //string, 标题
   }
 ]
 ```
 
 ---
 
-### 2. int数组
+### 2. struct嵌套
+
+```text
+GET /user/demo/struct_nested
+```
+
+__Response__:
+
+```javascript
+//StatusCode: 200 nested struct
+{  //object(handler.Struct1)
+  "Name": "abc",  //string
+  "Name2": "abc"  //string
+}
+```
+
+---
+
+### 3. int数组
 
 ```text
 GET /user/demo/int_array
@@ -63,7 +79,7 @@ __Response__:
 
 ---
 
-### 3. int
+### 4. int
 
 ```text
 GET /user/demo/int
@@ -79,7 +95,7 @@ __Response__:
 
 ---
 
-### 4. DemoMap
+### 5. DemoMap
 
 ```text
 GET /user/demo/map
@@ -92,6 +108,9 @@ __Response__:
 {  //object(handler.DemoData)
   "abc": {  //object(handler.DemoData)
     "count": 123,  //int
+    "DemoObject": {  //object(handler.DemoObject)
+      "name": "abc"  //string
+    },
     "description": "abc",  //string
     "float_array": [  //array[float64]
       1.23
@@ -103,12 +122,6 @@ __Response__:
     "map": {  //object(Map)
       "abc": 123  //int
     },
-    "object_1": {  //object(handler.DemoObject)
-      "name": "abc"  //string
-    },
-    "object_2": {  //object(handler.DemoObject)
-      "name": "abc"  //string
-    },
     "title": "abc"  //string, 标题
   }
 }

examples/svc-greeter/main.go

@@ -64,12 +64,21 @@ type Request struct {
 	Token string `header:"token"`
 } //请求对象
 
+type Struct1 struct {
+	Name string
+	Struct2
+}
+type Struct2 struct {
+	Name2 string
+}
+
 //@title 测试greeter
 //@api GET /greeter
 //@group greeter
 //@accept json
 //@request1 Request
-//@response 200 Response{data=TestData} "输出对象 dd"
+//@response 200 Struct1 "struct1"
+//@response1 200 Response{data=TestData} "输出对象 dd"
 //@response1 200 common.Response{data=TestData} "输出对象 dd"
 //@response1 500 Response{code=10010,msg="异常"} "出错了"
 //@response1 500 int 错误

examples/svc-user/handler/demo.go

@@ -34,6 +34,22 @@ func (h *DemoHandler) StructArray(w http.ResponseWriter, r *http.Request) {
 
 }
 
+type Struct1 struct {
+	Name string
+	Struct2
+}
+type Struct2 struct {
+	Name2 string
+}
+
+//@api GET /demo/struct_nested
+//@title struct嵌套
+//@group demo
+//@response 200 Struct1 "nested struct"
+func (h *DemoHandler) StructNested(w http.ResponseWriter, r *http.Request) {
+
+}
+
 //@api GET /demo/int_array
 //@title int数组
 //@group demo

examples/svc-user/main.go

@@ -58,6 +58,7 @@ func main() {
 		mux.HandleFunc("/user/demo/int_array", demo.IntArray)
 		mux.HandleFunc("/user/demo/map", demo.Map)
 		mux.HandleFunc("/user/demo/int", demo.Int)
+		mux.HandleFunc("/user/demo/struct_nested", demo.StructNested)
 	}
 
 	_ = http.ListenAndServe(":8000", mux)

gen/template/group_readme.tpl

@@ -7,5 +7,5 @@
 {{range $k,$v := .Groups}}
 {{add $k 1}}. [{{$v.Title}}](./apis-{{$v.Group}}.md)
 {{range $k2,$api := $v.Apis}}
-    - [{{$api.Title}}](./apis-{{$api.Group}}.md#{{add $k2 1}}-{{$api.Title}}) {{- if $api.Deprecated}}(Deprecated){{end}}
+    {{add $k 1}}.{{add $k2 1}}. [{{$api.Title}}](./apis-{{$api.Group}}.md#{{add $k2 1}}-{{$api.Title}}) {{- if $api.Deprecated}}(Deprecated){{end}}
 {{end}}{{end}}

operation_test.go

@@ -12,6 +12,12 @@ func TestOperation_ParseMatchResponseComment(t *testing.T) {
 		wantLen     int
 		matches     []string
 	}{
+		{
+			name:        "match response",
+			commentLine: `200 Response`,
+			wantLen:     4,
+			matches:     []string{"200", `Response`, ""},
+		},
 		{
 			name:        "match response",
 			commentLine: `200 common.Response`,

parser.go

@@ -380,9 +380,6 @@ func (parser *Parser) getTypeSchema(typeName string, file *ast.File, field *ast.
 	if err != nil {
 		return nil, err
 	}
-	if schema.Comment == "" {
-		schema.Comment = strings.TrimSuffix(typeSpecDef.TypeSpec.Comment.Text(), "\n")
-	}
 	return schema, nil
 }
 
@@ -414,12 +411,7 @@ func (parser *Parser) ParseDefinition(typeSpecDef *TypeSpecDef, field *ast.Field
 		if err != nil {
 			return nil, err
 		}
-		schema.Name = typeSpecDef.Name()
-		schema.FullName = typeSpecDef.FullName()
-		if field != nil {
-			schema.Name = field.Names[0].Name
-			schema.TagValue = getAllTagValue(field)
-		}
+
 		return schema, err
 	case *ast.Ident:
 		return parser.getTypeSchema(expr.Name, typeSpecDef.File, field, parentSchema)
@@ -545,32 +537,41 @@ func (parser *Parser) parseTypeExpr(file *ast.File, field *ast.Field, typeExpr a
 
 func (parser *Parser) parseStruct(typeSpecDef *TypeSpecDef, file *ast.File, fields *ast.FieldList, parentSchama *TypeSchema) (*TypeSchema, error) {
 	structSchema := &TypeSchema{
-		Name:        file.Name.Name,
+		Name:        typeSpecDef.Name(),
+		FullName:    typeSpecDef.FullName(),
+		PkgPath:     typeSpecDef.PkgPath,
+		FullPath:    typeSpecDef.FullPath(),
 		Type:        OBJECT,
+		Comment:     strings.TrimSuffix(typeSpecDef.TypeSpec.Comment.Text(), "\n"),
 		typeSpecDef: typeSpecDef,
 		Parent:      parentSchama,
 		Properties:  map[string]*TypeSchema{},
 	}
+
 	for _, field := range fields.List {
-		if len(field.Names) != 1 {
-			return nil, errors.New("error len(field.Names) != 1")
-		}
-		fmt.Println(field.Names[0].Name)
 		schema, err := parser.parseStructField(file, field, structSchema)
 		if err != nil {
 			return nil, err
 		}
-		// schema.Name = field.Names[0].Name
-		// schema.TagValue = getAllTagValue(field)
-		structSchema.Properties[strings.ToLower(schema.Name)] = schema
+		if field.Names == nil { //nested struct, replace with child properties
+			for _, p := range schema.Properties {
+				if _, ok := structSchema.Properties[strings.ToLower(p.Name)]; !ok { //if not exists key
+					structSchema.Properties[strings.ToLower(p.Name)] = p
+				}
+			}
+		} else {
+			structSchema.Properties[strings.ToLower(schema.Name)] = schema
+		}
 	}
 	return structSchema, nil
 }
 
 func (parser *Parser) parseStructField(file *ast.File, field *ast.Field, parentSchama *TypeSchema) (*TypeSchema, error) {
-	name := field.Names[0].Name
-	if !ast.IsExported(name) {
-		return nil, nil
+	if field.Names != nil {
+		name := field.Names[0].Name
+		if !ast.IsExported(name) {
+			return nil, nil
+		}
 	}
 	return parser.parseTypeExpr(file, field, field.Type, parentSchama)
 }

spec.go

@@ -79,10 +79,11 @@ type ApiResponseSpec struct {
 }
 
 type TypeSchema struct {
-	Name          string //xxRequest, xxResponse
+	Name          string //xxRequest, xxResponse, for example: RegisterRequest
 	Type          string //int, string, bool, object, array, any
 	FullName      string
-	PkgPath       string
+	PkgPath       string //for example: github.com/alovn/apidoc/examples/svc-user/handler
+	FullPath      string //for example: github.com/alovn/apidoc/examples/svc-user/handler.RegisterRequest
 	Comment       string
 	ArraySchema   *TypeSchema
 	Properties    map[string]*TypeSchema //object
@@ -185,7 +186,7 @@ func (v *TypeSchema) buildComment() string {
 		}
 		s += fmt.Sprintf("%s[%s]", ARRAY, arrayName)
 	} else if len(v.Properties) > 0 { //object
-		s += fmt.Sprintf("%s(%s)", v.Type, v.PkgPath+v.FullName)
+		s += fmt.Sprintf("%s(%s)", v.Type, v.FullName)
 	} else {
 		s += v.Type
 	}