如何在 OpenAPI (Swagger) 中指定多个 404 原因？

Question

我正在为嵌套资源（属于交付的内容）定义路径。如果客户端收到 404，可能是因为未找到交付 ID，或者交付不包含指定类型的任何内容。

如何使用 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'

...但是当我从 Swagger 编辑器中保存 JSON 时，它会丢弃除最后一个 ("delivery did not contain any articles") 之外的所有 404 响应。

Answer 1

OpenAPI/Swagger 2.0 不允许每个状态代码有多种响应类型，但 OpenAPI 3.0 支持。

在 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"
}

如何在 OpenAPI (Swagger) 中指定多个 404 原因？

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

swagger

swagger-2.0

openapi