Я определяю путь для вложенного ресурса (контент, принадлежащий доставке). Если клиент получает 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, он отбрасывает все 404 ответа, кроме последнего («доставка не содержала статей»).