我定义了嵌套资源的路径(属于交付的内容)。如果客户端获得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响应("传递不包含任何文章")。
答案 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"
}