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

【问题标题】：go-swagger generate spec for route with path parametergo-swagger 为带有路径参数的路由生成规范
【发布时间】：2016-02-16 12:15:21
【问题描述】：

我正在尝试使用 go-swagger 生成符合 Swagger2.0 specification 的 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)

struct wrapping bar 参数：

// 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 的 doc cmets 以实现这一目标？是否有任何文档描述了 go-swagger 的确切 cmets 格式？

【问题讨论】：

标签： json rest go swagger

【解决方案1】：

尝试将您的端点操作 id ('updateBar') 添加为参数操作 id。比如：

// swagger:parameters updateBar
type BarParam struct {

    // aaaa
    // in: path
    bar string
}

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

【讨论】：

【解决方案2】：

如果你想切换 Bar 为小写，你必须设置：

// swagger:parameters updateBar
type BarParam struct {
    Bar string `json:"bar"`
}

【讨论】：