How to specify multiple 404 causes in OpenAPI (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"
}