Открыть API POST с параметром пути

Я пытаюсь написать спецификацию Open API с помощью Swagger-ui (swagger версии 2.0), и я не уверен, как представить параметр POST с параметром path

POST /ping/{text}

Моя спецификация выглядит следующим образом,

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Mock API
  description: Mock API 
  version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /ping:
    get:
      summary: Ping
      description: |
        Respond to PING requests, similar to heart beat
      parameters:
        - name: path  
          in: path
          description: String input for echo service
          required: false
          type: string
      tags:
        - ping
      responses:
        200:
          description: The text passed in the request
          schema:
            type: string
        default:
          description: Empty response for request passed
          schema:
            type: string

И пользовательский интерфейс swagger показывает ошибку следующим образом:

 code:  "ONE_OF_MISSING"
 message:  "Not a valid parameter definition"

но если я изменю его на in: query, ошибка исчезнет. Что я делаю не так? или как правильно указать параметр пути в открытой спецификации API?


rest jsonschema swagger-ui swagger-2.0 swagger-editor
person g0c00l.g33k    schedule 29.02.2016    source источник

Ответы (2)


arrow_upward
1
arrow_downward

В документ необходимо внести несколько изменений, чтобы он соответствовал спецификации Open API.

1- Поле name должно соответствовать сегменту пути (т.е. text

Если это «путь», поле name ДОЛЖНО соответствовать связанному сегменту пути из поля пути в объекте «Пути». Дополнительную информацию см. в разделе Шаблоны путей.

2- required: true следует добавить.

Если параметр находится в «пути», это свойство является обязательным, и его значение ДОЛЖНО быть истинным.

3- Если вы хотите задокументировать POST /ping/{text}, get необходимо изменить на post. Также к пути следует добавить сегмент пути (т.е. /{text).

Вот окончательный документ Swagger после описанных выше изменений:

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Mock API
  description: Mock API 
  version: "1.0.0"
# the domain of the service
host: api.mock.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:
  /ping/{text}:
    post:
      summary: Ping
      description: |
        Respond to PING requests, similar to heart beat
      parameters:
        - name: text  
          in: path
          description: String input for echo service
          required: true
          type: string
      tags:
        - ping
      responses:
        200:
          description: The text passed in the request
          schema:
            type: string
        default:
          description: Empty response for request passed
          schema:
            type: string
person Navid Shakibapour    schedule 04.03.2016

arrow_upward
0
arrow_downward

В соответствии со спецификацией кажется, что «требуемый» должен быть истинным, если вы установите «в: путь».

Подробности можно найти здесь: http://swagger.io/specification/#parameterObject

person Daniel    schedule 03.03.2016
comment
Переключение с required на true по-прежнему показывает ту же ошибку :( - person g0c00l.g33k; 04.03.2016