如何不在几乎所有路径中复制粘贴 3 个通用错误响应? [英] How not to copy-paste 3 generic error responses in almost all paths?
本文介绍了如何不在几乎所有路径中复制粘贴 3 个通用错误响应?的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!
问题描述
我希望我的几乎所有路径都具有以下 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.
这篇关于如何不在几乎所有路径中复制粘贴 3 个通用错误响应?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!
查看全文