feat: request parameters, suppport header, query, form, param

examples/docs/apis-account.md

@@ -6,20 +6,24 @@
 
 ### 用户注册接口
 
+用户注册接口说明
+
 author: _alovn_
 
 ```text
 POST /user/account/register
 ```
 
-**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--
-**password**|_form_|string|true|required|"abc"|密码
-**username**|_form_|string|true|required|"abc"|用户名
+__from__|_query_|string|false|||test
+__password__|_form_|string|true|required|"abc"|密码
+__username__|_form_|string|true|required|"abc"|用户名
+__x-request-id__|_header_|string|false|||request id
 
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 注册成功返回数据
@@ -42,6 +46,8 @@ parameters|modes|type|required|validate|example|description
 }
 ```
 
+---
+
 ### 用户登录接口
 
 author: _alovn_
@@ -50,15 +56,15 @@ author: _alovn_
 POST /user/account/login
 ```
 
-**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--
-**password**|_form_|string|true|required|"abc"|登录密码
-**username**|_form_|string|true|required|"abc"|登录用户名
-**validate_code**|_form_|string|false||"abc"|验证码
+__password__|_form_|string|true|required|"abc"|登录密码
+__username__|_form_|string|true|required|"abc"|登录用户名
+__validate_code__|_form_|string|false||"abc"|验证码
 
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 登录成功返回数据
@@ -78,3 +84,5 @@ parameters|modes|type|required|validate|example|description
   "msg": "password_error",  //string, 返回消息
 }
 ```
+
+---

examples/docs/apis-address.md

@@ -12,14 +12,14 @@ author: _alovn_
 POST /user/address/create
 ```
 
-**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--
-**address**|_form_|string|true|required|"abc"|地址
-**city_id**|_form_|int64|true|required|123|城市ID
+__address__|_form_|string|true|required|"abc"|地址
+__city_id__|_form_|int64|true|required|123|城市ID
 
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 
@@ -29,6 +29,8 @@ parameters|modes|type|required|validate|example|description
 }
 ```
 
+---
+
 ### 更新地址接口
 
 author: _alovn_
@@ -37,14 +39,14 @@ author: _alovn_
 POST /user/address/update
 ```
 
-**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--
-**address**|_form_|string|true|required|"abc"|地址
-**id**|_form_|int64|true|required|123|地址ID
+__address__|_form_|string|true|required|"abc"|地址
+__id__|_form_|int64|true|required|123|地址ID
 
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 
@@ -54,6 +56,8 @@ parameters|modes|type|required|validate|example|description
 }
 ```
 
+---
+
 ### 删除地址接口
 
 author: _alovn_
@@ -62,13 +66,13 @@ author: _alovn_
 POST /user/address/delete
 ```
 
-**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--
-**id**|_form_|int64|true|required|123|地址ID
+__id__|_form_|int64|true|required|123|地址ID
 
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 
@@ -78,6 +82,8 @@ parameters|modes|type|required|validate|example|description
 }
 ```
 
+---
+
 ### 获取地址信息
 
 author: _alovn_
@@ -86,13 +92,13 @@ author: _alovn_
 GET /user/address/get/:id
 ```
 
-**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--
-**id**|_param_|int64|false||123|地址ID
+__id__|_param_|int64|false||123|地址ID
 
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 
@@ -107,17 +113,21 @@ parameters|modes|type|required|validate|example|description
 }
 ```
 
+---
+
 ### 获取地址列表
 
+___Deprecated___
+
+获取收货地址列表
+
 author: _alovn_
 
 ```text
 GET /user/address/list
 ```
 
-
-
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 
@@ -133,3 +143,5 @@ GET /user/address/list
   "msg": "success"  //string, 返回消息
 }
 ```
+
+---

examples/docs/apis-profile.md

@@ -12,9 +12,7 @@ author: _alovn_
 GET /user/profile/get
 ```
 
-
-
-**Response**:
+__Response__:
 
 ```json
 // StatusCode: 200 
@@ -30,3 +28,5 @@ GET /user/profile/get
   "msg": "success"  //string, 返回消息
 }
 ```
+
+---

examples/svc-user/handler/account.go

@@ -29,9 +29,12 @@ type RegisterResponse struct {
 //@title 用户注册接口
 //@group account
 //@request RegisterRequest
+//@header x-request-id string false "request id"
+//@query from string false "test"
 //@response 200 common.Response{code=0,msg="success",data=RegisterResponse} "注册成功返回数据"
 //@response 200 common.Response{code=10011,msg="password format error"} "密码格式错误"
 //@author alovn
+//@desc 用户注册接口说明
 func (h *AccountHandler) Register(w http.ResponseWriter, r *http.Request) {
 	res := common.NewResponse(200, "注册成功", &RegisterResponse{
 		Username:   "abc",

examples/svc-user/handler/address.go

@@ -92,6 +92,8 @@ func (h *AddressHandler) Get(w http.ResponseWriter, r *http.Request) {
 //@group address
 //@response 200 common.Response{code=0,msg="success",data=[]AddressResponse}
 //@author alovn
+//@desc 获取收货地址列表
+// Deprecated: or use @deprecated
 func (h *AddressHandler) List(w http.ResponseWriter, r *http.Request) {
 	addresses := []AddressResponse{}
 	res := common.NewResponse(200, "删除成功", addresses)

gen/template/group_apis.tpl

@@ -3,25 +3,46 @@
 {{.Description}}
 
 ## apis
-{{range $k,$v := .Apis}}
+{{- range $k,$v := .Apis}}
+
 ### {{$v.Title}}
-{{if $v.Author}}
+
+{{- if $v.Deprecated}}
+
+___Deprecated___
+{{- end}}
+
+{{- if $v.Description}}
+
+{{$v.Description}}
+{{- end}}
+
+{{- if $v.Author}}
+
 author: _{{$v.Author}}_
-{{end}}
+{{- end}}
+
 ```text
 {{$v.HTTPMethod}} {{$v.FullURL}}
 ```
+{{- if $v.Requests.Parameters}}
 
-{{if $v.Requests.Parameters}}**Request**:
+__Request__:
 
-parameters|modes|type|required|validate|example|description
+parameter|parameterType|dataType|required|validate|example|description
 --|--|--|--|--|--|--{{range $p:= $v.Requests.Parameters}}
-**{{$p.Name}}**|_{{$p.Modes}}_|{{$p.Type}}|{{$p.Required}}|{{$p.Validate}}|{{$p.Example}}|{{$p.Description}}{{end}}{{end}}
+__{{$p.Name}}__|_{{$p.ParameterTypes}}_|{{$p.DataType}}|{{$p.Required}}|{{$p.Validate}}|{{$p.Example}}|{{$p.Description}}{{end}}{{end}}
+{{- if $v.Responses}}
+
+__Response__:
+{{- range $res := $v.Responses}}
 
-{{if $v.Responses}}**Response**:
-{{range $res := $v.Responses}}
 ```json
 // StatusCode: {{$res.StatusCode}} {{$res.Description}}
 {{$res.Examples}}
 ```
-{{end}}{{end}}{{end}}
+{{- end}}
+
+---
+{{- end}}
+{{- end}}

operation.go

@@ -14,6 +14,8 @@ var (
 	requestPattern  = regexp.MustCompile(`([\w\-.\\\[\]]+)\s*(.*)?`)
 	// ResponseType{data1=Type1,data2=Type2}.
 	combinedPattern = regexp.MustCompile(`^([\w\-./\[\]]+){(.*)}$`)
+	// requestId string true "comment"
+	paramPattern = regexp.MustCompile(`(\S+)\s+([\S.]+)\s+(\w+)\s+"([^"]+)"`)
 )
 
 // Operation describes a single API operation on a path.
@@ -68,7 +70,9 @@ func (operation *Operation) ParseComment(comment string, astFile *ast.File) erro
 		return operation.ParseRequestComment(lineRemainder, astFile)
 	case successAttr, failureAttr, responseAttr:
 		return operation.ParseResponseComment(lineRemainder, astFile)
-	case deprecatedAttr:
+	case headerAttr, queryAttr, paramAttr, formAttr:
+		return operation.ParseParametersComment(strings.TrimPrefix(lowerAttribute, "@"), lineRemainder, astFile)
+	case deprecatedAttr, "deprecated:":
 		operation.Deprecated = true
 	}
 
@@ -137,16 +141,16 @@ func (operation *Operation) ParseRequestComment(commentLine string, astFile *ast
 		for _, p := range schema.Properties {
 			for pMode, pName := range p.Tags {
 				if param, ok := operation.Requests.Parameters[pName]; ok {
-					param.modes = append(param.modes, pMode)
+					param.parameterTypes = append(param.parameterTypes, pMode)
 				} else {
 					operation.Requests.Parameters[pName] = &ApiParameterSpec{
-						Name:        pName,
-						Required:    p.Required,
-						Description: p.Comment,
-						Validate:    p.Validate,
-						Example:     p.Example,
-						modes:       []string{pMode},
-						Type:        p.Type,
+						Name:           pName,
+						Required:       p.Required,
+						Description:    p.Comment,
+						Validate:       p.Validate,
+						Example:        p.Example,
+						parameterTypes: []string{pMode},
+						DataType:       p.Type,
 					}
 				}
 			}
@@ -155,6 +159,31 @@ func (operation *Operation) ParseRequestComment(commentLine string, astFile *ast
 	}
 }
 
+//ParseParametersComment parses parameters (@header, @param, @query, @form)
+//@param [name] [type] [required] [comment]
+//@query demo int true "测试参数"
+func (operation *Operation) ParseParametersComment(parameterType, commentLine string, astFile *ast.File) error {
+	matches := paramPattern.FindStringSubmatch(commentLine)
+	if len(matches) != 5 {
+		return fmt.Errorf("missing required param comment parameters \"%s\"", commentLine)
+	}
+	name := matches[1]
+	dataType := matches[2]
+	required := strings.ToLower(matches[3]) == "true"
+	description := matches[4]
+	if _, ok := operation.Requests.Parameters[name]; !ok {
+		operation.Requests.Parameters[name] = &ApiParameterSpec{
+			Name:        name,
+			DataType:    dataType,
+			Required:    required,
+			Description: description,
+			// Example:        getExampleValue(dataType, ""),
+			parameterTypes: []string{parameterType},
+		}
+	}
+	return nil
+}
+
 // ParseResponseComment parses comment for given `response` comment string.
 func (operation *Operation) ParseResponseComment(commentLine string, astFile *ast.File) error {
 	operation.parser.clearStructStack()

parser.go

@@ -23,6 +23,10 @@ const (
 	descriptionAttr = "@desc"
 	acceptAttr      = "@accept"
 	requestAttr     = "@request"
+	queryAttr       = "@query"
+	paramAttr       = "@param"
+	headerAttr      = "@header"
+	formAttr        = "@form"
 	successAttr     = "@success"
 	failureAttr     = "@failure"
 	responseAttr    = "@response"