go-swagger generate spec для маршрута с параметром пути

Question

Я пытаюсь создать документацию json API, соответствующую , используя go-swagger.

У меня есть проблема, генерирующую JSON документ для маршрута с путем парами, который выглядит следующим образом:

PUT/Foo/{бар}

В настоящее время мой 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 параметр обертывание бар:

// 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" 
       } 
      ] 
     } 
    } 

Как я могу изменить комментарии к doc для go-swagger для достижения этого? Есть ли какая-либо документация, описывающая формат точных комментариев для go-swagger?

Answer 1

Попробуйте добавить идентификатор операции конечной точки ('updateBar') в качестве идентификатора операции параметра. Что-то вроде:

// swagger:parameters updateBar 
type BarParam struct { 

    // aaaa 
    // in: path 
    bar string 
} 

И удалить «Параметры» из вашей конечной точки развязность документ

Answer 2

Если вы хотите переключить панель в нижнем регистре, вы должны установить:

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