go-swagger 为带有路径参数的路由生成规范

Question

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

我在为路径参数生成 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 updateBartype BarParam struct {    // aaaa    // in: path    bar string}并从您的端点 swagger 文档中删除“参数”

Answer 2

如果要将 Bar 切换为小写，则必须设置：// swagger:parameters updateBartype BarParam struct {    Bar string `json:"bar"`}