doub1ejack doub1ejack - 13 days ago 9
reST (reStructuredText) Question

How to specify multiple 404 causes in swagger?

I'm defining a path for a nested resource (content belonging to a delivery). If the client gets a 404 it could either be because the delivery id was not found or the delivery did not contain any content of the specified type.

How do I model that in swagger yaml?

I've got this right now...

'/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'


... but when I save the json from the swagger editor dropped the all 404 responses except the last one ("delivery did not contain any articles").

Answer

Multiple response types per status code are not allowed in Swagger. This is by design.

What you can do is have a single 404 response code that describes multiple options, such as:

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

where the Error object can be:

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

{
  "status": 404,
  "type": "NoArticlesInDeliveryError"
  "message": "delivery did not contain any articles"
}
Comments