Как указать несколько причин 404 в OpenAPI (Swagger)?

Я определяю путь для вложенного ресурса (контента, принадлежащего доставке). Если клиент получает ошибку 404, это может быть связано либо с тем, что идентификатор доставки не был найден, либо потому, что доставка не содержала какого-либо содержимого указанного типа.

Как смоделировать это с помощью OpenAPI (YAML)?

Я получил это прямо сейчас ...

 paths:
  '/deliveries/{id}/content/articles':
    get:
      summary: Retrieves articles from a delivery
      description: Retrieves all articles from a single delivery
      [...]
      responses:
        '200':
          description: articles found
          schema:
            $ref: '#/definitions/Article'
        '404':
          description: delivery not found
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: delivery did not contain any articles
          schema:
            $ref: '#/definitions/Error'

... но когда я сохраняю JSON из редактора Swagger Editor, он отбрасывает все 404 ответа, кроме последнего («доставка не содержала никаких статей»).


openapi swagger swagger-2.0
person doub1ejack    schedule 16.11.2016    source источник

Ответы (1)


arrow_upward
5
arrow_downward

Множественные типы ответов для каждого кода состояния не разрешены в OpenAPI / Swagger 2.0, но поддерживаются в OpenAPI 3.0 с помощью oneOf.

В OpenAPI 2.0 у вас может быть только одна схема для ответа 404:

      responses:
        '404':
          description: delivery not found, or delivery did not contain any articles
          schema:
            $ref: '#/definitions/Error'

...
definitions:
  Error:
    type: object
    properties:
      status:
        type: integer
      type:
        type: string
      message:
        type: string

где полезная нагрузка Error может быть, например:

{
  "status": 404,
  "type": "DeliveryNotFoundError",
  "message": "delivery not found"
}


{
  "status": 404,
  "type": "NoArticlesInDeliveryError",
  "message": "delivery did not contain any articles"
}
person Helen    schedule 18.11.2016
comment
Не могли бы вы показать фактическое определение ошибки YAML, пожалуйста? - person Gargoyle; 28.01.2017
comment
Добавлено определение ошибки. - person Helen; 14.12.2017
comment
Это не отвечает на вопрос. Вопрос заключался в том, как указать несколько ответов для одного и того же кода с одним и тем же типом ответа, но с разными описаниями. См. Пример в вопросе. Единственное различие между двумя 404 - это описание, тип ответа идентичен. - person Zoran Pavlovic; 04.11.2019