json - go-swagger 使用路径参数为路由生成规范

Question

我正在尝试生成符合 Swagger2.0 specification 的 json API 文档使用 go-swagger .

我在为路径参数生成 JSON 文档时遇到问题，如下所示:

PUT /foo/{bar}

目前我的 godoc 看起来像这样:

// Update bar in foo
// swagger:route PUT /foo/{bar} updateBar
//     Parameters:
//       bar: barParam
//     Responses:
//       500: myErrorResponse
func (h *handler) update(req *http.Request, params martini.Params) (int, string)

结构包装条参数:

// swagger:parameters barParam
type BarParam struct {

    // aaaa
    // in: path
    bar string
}

当我运行时:

swagger generate spec -o ./swagger.json

当前生成的 JSON 如下所示:

    "/foo/{bar}": {
        "put": {
            "description": "bar: barParam",
            "operationId": "updateBar",
            "responses": {
                "500": {
                    "$ref": "#/responses/myErrorResponse"
                }
            },
            "summary": "Parameters:"
        }
    }

但我想生成以下 JSON(符合 Swagger2.0):

    "/v2/foo/{bar}": {
        "put": {
            "operationId": "updateBar",
            "responses": {
                "500": {
                    "$ref": "#/responses/myErrorResponse"
                }
            },
            "parameters": [
                {
                    "in": "path",
                    "name": "bar",
                    "description": "aaaa",
                    "required": true,
                    "type": "string"
                }
            ]
        }
    }

如何修改 go-swagger 的文档注释来实现这一点？是否有任何文档描述了 go-swagger 的确切注释格式？

Answer 1

尝试将您的端点操作 ID ('updateBar') 添加为参数操作 ID。像这样的东西:

// swagger:parameters updateBar
type BarParam struct {

    // aaaa
    // in: path
    bar string
}

并从您的端点 swagger 文档中删除“参数”