How to specify multiple 404 causes in OpenAPI (Swagger)? - swagger

Question

I'm defining a path for a nested resource (content belonging to a delivery). If the client gets a 404 it could either because the delivery ID was not found, or the delivery did not contain any content of the specified type.
How do I model that using OpenAPI (YAML)?
I've got this right now...
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'
... but when I save the JSON from the Swagger Editor, it dropps the all 404 responses except the last one ("delivery did not contain any articles").

Answer 1

Multiple response types per status code are not allowed in OpenAPI/Swagger 2.0, but are supported in OpenAPI 3.0 by using oneOf.
In OpenAPI 2.0, you can only have a single schema for a 404 response:
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
where the Error payload can be, say:
{
"status": 404,
"type": "DeliveryNotFoundError",
"message": "delivery not found"
}
{
"status": 404,
"type": "NoArticlesInDeliveryError",
"message": "delivery did not contain any articles"
}