如何在OpenAPI(Swagger)中指定多个404原因? [英] How to specify multiple 404 causes in OpenAPI (Swagger)?
问题描述
我正在为嵌套资源(属于交付的内容)定义路径.如果客户端收到404,则可能是因为找不到交付ID,或者交付不包含任何指定类型的内容.
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.
如何使用OpenAPI(YAML)建立模型?
How do I model that using 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响应.
... 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").
推荐答案
OpenAPI/Swagger 2.0中不允许每个状态码有多种响应类型,但OpenAPI 3.0中支持每种状态代码
Multiple response types per status code are not allowed in OpenAPI/Swagger 2.0, but are supported in OpenAPI 3.0 by using oneOf
.
在OpenAPI 2.0中,您只能为404响应提供一个架构:
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
Error
有效负载所在的位置,例如:
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"
}
这篇关于如何在OpenAPI(Swagger)中指定多个404原因?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!