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

本文介绍了如何在OpenAPI(Swagger)中指定多个404原因?的处理方法，对大家解决问题具有一定的参考价值，需要的朋友们下面随着小编来一起学习吧！ 问题描述

我正在为嵌套资源(属于交付的内容)定义路径.如果客户端收到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中支持每种状态代码使用oneOf .

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