如何为POST请求的嵌套JSON参数生成Swagger文档

我需要POST请求的参数是如下嵌套JSON结构：

{
        "adnxs_uid": "10589",
        "ra":"1.2.3.4",
        "event": {
            
        }
}

我原本在Go函数里用Swagger注释定义参数，尝试生成嵌套结构，但结果不符合预期：

// swagger:route POST /1.0/log version-1 logPost
    //
    // This will log an event coming from the web
    // The request will be sent as a POST request
    //
    //     Consumes:
    //     - application/json
    //
    //     Produces:
    //     - application/json
    //
    //     Schemes: https
    //
    //     Parameters:
    //       + name: event
    //         in: body
    //         description: event to be logged, sent as JSON string
    //         type: string
    //         required: true
    //         schema:
    //           type: string
    //       + name: adnxs_uid
    //         in: body
    //         description: appnexus user id
    //         type: string
    //         required: false
    //         schema:
    //           type: string
    //       + name: ra
    //         in: body
    //         description: ip address of the user
    //
    //     Responses:
    //       200: body:StringBody Event logged successfully
    //       400: body:StringBody Invalid JSON structure
    //       401: body:StringBody Unauthorized, either key param is missing or is invalid

使用命令 swagger generate spec -o ../swagger.json --scan-models 生成后，参数结构是分散的：

{
            "description": "event to be logged, sent as JSON string",
            "name": "event",
            "in": "body",
            "required": true,
            "schema": {
              "description": "event to be logged, sent as JSON string",
              "type": "string"
            }
          },
          {
            "description": "appnexus user id",
            "name": "adnxs_uid",
            "in": "body",
            "schema": {
              "description": "appnexus user id",
              "type": "string"
            }
          },
          {
            "description": "ip address of the user",
            "name": "ra",
            "in": "body"
          }
        ]

我期望生成的是嵌套的对象结构：

"schema": { "type": "object", "properties": { "event": { "type": "object", "description": "..." }, "adnxs_uid": { "type": "string", "description": "..." }, "ra": { "type": "string", "description": "..." } } }

调整方案 #

你需要将整个请求体定义为一个单独的body参数，在其schema内部统一定义嵌套的对象和属性，而非拆分多个body参数。以下两种方法都可以实现需求：

方法1：直接在Swagger注释中定义schema

修改后的Swagger注释：

// swagger:route POST /1.0/log version-1 logPost
    //
    // This will log an event coming from the web
    // The request will be sent as a POST request
    //
    //     Consumes:
    //     - application/json
    //
    //     Produces:
    //     - application/json
    //
    //     Schemes: https
    //
    //     Parameters:
    //       + name: requestBody
    //         in: body
    //         description: event to be logged, sent as JSON object
    //         required: true
    //         schema:
    //           type: object
    //           properties:
    //             adnxs_uid:
    //               type: string
    //               description: appnexus user id
    //             ra:
    //               type: string
    //               description: ip address of the user
    //             event:
    //               type: object
    //               description: event details
    //           required:
    //             - event
    //
    //     Responses:
    //       200: body:StringBody Event logged successfully
    //       400: body:StringBody Invalid JSON structure
    //       401: body:StringBody Unauthorized, either key param is missing or is invalid

方法2：使用Go结构体绑定（更推荐）

通过定义Go结构体并绑定Swagger注释，生成的spec会更规范且易于维护：

1. 定义请求结构体：

// swagger:model LogRequest
type LogRequest struct {
    // Appnexus用户ID
    // optional: true
    AdnxsUID string `json:"adnxs_uid"`
    // 用户IP地址
    // optional: true
    RA string `json:"ra"`
    // 事件详情（必填）
    // required: true
    Event map[string]interface{} `json:"event"`
}

2. 修改函数的Swagger注释，引用该结构体作为请求体：

// swagger:route POST /1.0/log version-1 logPost
    //
    // This will log an event coming from the web
    // The request will be sent as a POST request
    //
    //     Consumes:
    //     - application/json
    //
    //     Produces:
    //     - application/json
    //
    //     Schemes: https
    //
    //     Parameters:
    //       + name: body
    //         in: body
    //         description: event to be logged
    //         required: true
    //         schema:
    //           "$ref": "#/definitions/LogRequest"
    //
    //     Responses:
    //       200: body:StringBody Event logged successfully
    //       400: body:StringBody Invalid JSON structure
    //       401: body:StringBody Unauthorized, either key param is missing or is invalid

完成注释修改后，重新执行生成命令：

swagger generate spec -o ../swagger.json --scan-models

这样生成的Swagger spec就会包含你期望的嵌套对象结构。

内容的提问来源于stack exchange，提问作者Rajat Singh