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

时间:2016-11-16 19:27:59

标签: swagger swagger-2.0 openapi

我定义了嵌套资源的路径(属于交付的内容)。如果客户端获得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时,它会删除除最后一个之外的所有404响应("传递不包含任何文章")。

1 个答案:

答案 0 :(得分:3)

OpenAPI / Swagger 2.0中不允许每个状态代码有多种响应类型,但OpenAPI 3.0 by using oneOf支持这些类型。

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