英文:
go-swagger generate spec for route with path parameter
问题
我正在尝试使用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)
包装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:"
}
}
但我想生成以下符合Swagger2.0规范的JSON：
"/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确切注释格式的文档？
英文:
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?
答案1
得分: 0
尝试将您的端点操作ID（'updateBar'）作为参数操作ID添加进去。类似这样：
// swagger:parameters updateBar
type BarParam struct {
// aaaa
// in: path
bar string
}
并且从您的端点Swagger文档中删除'Parameters'。
英文:
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
答案2
得分: 0
如果你想将 Bar 转换为小写，你需要进行以下设置：
// swagger:parameters updateBar
type BarParam struct {
Bar string `json:"bar"`
}
英文:
If you want to Switch Bar to lowercase, you have to set :
// swagger:parameters updateBar
type BarParam struct {
Bar string `json:"bar"`
}
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库，让每个人都能够通过互相帮助和分享经验来进步。
评论