go-swagger使用path参数生成路线规格

Question

I am trying to generate json API documentation compliant with Swagger2.0 specification using go-swagger.

I have a problem generating JSON doc for the route with path param which looks like this:

PUT /foo/{bar}

Currently my godoc looks like this:

// 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 parameter:

// swagger:parameters barParam
type BarParam struct {

    // aaaa
    // in: path
    bar string
}

When I run:

swagger generate spec -o ./swagger.json

The generated JSON currently looks like this:

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

But I want to generate the following JSON (compliant with Swagger2.0):

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

How can I modify the doc comments for go-swagger to achieve that? Is there any documentation that describes the exact comments format for go-swagger?

Answer 1

Try to add your endpoint operatin id ('updateBar') as a parameter operation id. Something like:

// swagger:parameters updateBar
type BarParam struct {

    // aaaa
    // in: path
    bar string
}

And remove 'Parameters' from your endpoint swagger doc