go-swagger – 请求体中的对象数组

huangapple go评论78阅读模式
英文:

go-swagger - array of objects in request body

问题

我正在使用go-swagger来为我们的API生成Swagger文件。我一直在尝试为一个接收对象数组的API添加注释,但是go-swagger似乎无法识别它。

我的请求在JSON格式中如下所示:

{
  [
    {
      "name": "title1",
      "label": "tag1",
      "sort": true
    },
    {
      "name": "title2",
      "label": "tag2",
      "sort": true
    }
  ]
}

这是我目前的注释:

// swagger:route POST /admin/qc QC createQC
//
// 创建一个新的QC。
//
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
//     Schemes: https
//
//     Deprecated: false
//
//
//     Parameters:
// 		 + name: Authorization
// 		   in: header
// 		   required: true
// 		   type: string
//
// 		 + name: input
// 		   in: body
// 		   required: true
// 		   type: array
//         items: QC
//
//     Responses:
//       200: StatusOK

这是生成的Swagger文件:

/admin/qc:
    post:
      consumes:
      - application/json
      operationId: createQC
      parameters:
      - in: header
        name: Authorization
        required: true
        type: string
      - in: body
        name: input
        required: true
        schema:
          type: array
      produces:
      - application/json
      responses:
        "200":
          description: StatusOK
          schema:
            $ref: '#/definitions/StatusOK'
      schemes:
      - https
      summary: 创建一个新的QC。
      tags:
      - QC

go-swagger在这个注释中没有识别到items类型。很遗憾,无法更改此API的请求类型。

有人知道我应该如何注释吗?

英文:

I'm using go-swagger for generating swagger file for our APIs
I've been trying to add comments for an API that gets an array of objects in request but the go-swagger seems like is not recognizing it

my request looks like this in JSON format:

{
  [
    {
      "name": "title1",
      "label": "tag1",
      "sort": true
    },
    {
      "name": "title2",
      "label": "tag2",
      "sort": true
    }
  ]
}

<br>
this is what my comments looks like right now

// swagger:route POST /admin/qc QC createQC
//
// Creates a new QC.
//
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
//     Schemes: https
//
//     Deprecated: false
//
//
//     Parameters:
// 		 + name: Authorization
// 		   in: header
// 		   required: true
// 		   type: string
//
// 		 + name: input
// 		   in: body
// 		   required: true
// 		   type: array
//         items: QC
//
//     Responses:
//       200: StatusOK

this is the generated swagger file

/admin/qc:
    post:
      consumes:
      - application/json
      operationId: createQC
      parameters:
      - in: header
        name: Authorization
        required: true
        type: string
      - in: body
        name: input
        required: true
        schema:
          type: array
      produces:
      - application/json
      responses:
        &quot;200&quot;:
          description: StatusOK
          schema:
            $ref: &#39;#/definitions/StatusOK&#39;
      schemes:
      - https
      summary: Creates a new QC.
      tags:
      - QC

the go-swagger does not pick up the items type in this annotation.
the option to change the request type of this API is not available unfortunately.

anybody has any idea how I should annotate this?

答案1

得分: 0

为了注释这种类型的请求,您需要定义一个新的结构,如下所示:

// swagger:parameters createQC
type CreateQCReqs struct {
    // in: body
    Body []*CreateQCReq
}

您需要使用swagger:parameters注释,后跟API的操作ID。
然后,您需要使用所需的数据类型定义Body字段。在我的例子中,它是一个CreateQCReq的数组。
之后,您需要在swagger:route中删除body参数,否则您的swagger文件中的body字段将生成两次。

英文:

in order to annotate this type of request you will need to define a new struct like this:

// swagger:parameters createQC
type CreateQCReqs struct {
	// in: body
	Body []*CreateQCReq
}

you need to annotate this with swagger:parameters followed by operation id of the api<br>
after that you need to define Body field with your desired data type
in my case it was an array of CreateQCReq<br>
after that you need to remove the body parameter in your swagger:route, otherwise the body field in your swagger file will be generated 2 times

huangapple
  • 本文由 发表于 2022年5月23日 16:00:28
  • 转载请务必保留本文链接:https://go.coder-hub.com/72345104.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定