由网友(痛失吾爱)分享简介:我希望我的几乎所有路径都具有以下 3 个通用错误响应.我如何在 Swagger 中描述它而不到处复制粘贴这些行?I want almost all my paths to have the following 3 generic error responses. How do I describe that in S...
我希望我的几乎所有路径都具有以下 3 个通用错误响应.我如何在 Swagger 中描述它而不到处复制粘贴这些行?
I want almost all my paths to have the following 3 generic error responses. How do I describe that in Swagger without copypasting these lines everywhere?
401:
description: The requester is unauthorized.
schema:
$ref: '#/definitions/Error'
500:
description: "Something went wrong. It's server's fault."
schema:
$ref: '#/definitions/Error'
503:
description: Server is unavailable. Maybe there is maintenance?
schema:
$ref: '#/definitions/Error'
我如何在请求中使用它的示例:
Example of how I use this in a request:
paths:
/roles:
get:
summary: Roles
description: |
Returns all roles available for users.
responses:
200:
description: An array with all roles.
schema:
type: array
items:
$ref: '#/definitions/Role'
401:
description: The requester is unauthorized.
schema:
$ref: '#/definitions/Error'
500:
description: "Something went wrong. It's server's fault."
schema:
$ref: '#/definitions/Error'
503:
description: Server is unavailable. Maybe there is maintenance?
schema:
$ref: '#/definitions/Error'
推荐答案
看来我可以添加以下全局响应定义:
Looks like I can add the following global response definition:
# An object to hold responses that can be used across operations.
# This property does not define global responses for all operations.
responses:
NotAuthorized:
description: The requester is unauthorized.
schema:
$ref: '#/definitions/Error'
但是我仍然需要在这样的路径中引用它:
However I will still need to reference it in paths like this:
401:
$ref: '#/responses/NotAuthorized'
在 OpenAPI 3.0 中也是一样,除了它使用 #/components/responses/...
而不是 #/responses/...
:
openapi: 3.0.0
# An object to hold responses that can be used across operations.
# This property does not define global responses for all operations.
components:
responses:
NotAuthorized:
description: The requester is unauthorized.
schema:
$ref: '#/components/schemas/Error'
# Then, in operation responses, use:
...
401:
$ref: '#/components/responses/NotAuthorized'
OpenAPI 规范存储库中还有一个开放的功能请求,以添加对全局的支持/操作的默认响应.
There's also an open feature request in the OpenAPI Specification repository to add support for global/default responses for operations.
相关推荐
最新文章