swagger: "2.0"
...
securityDefinitions:
accountId:
type: apiKey
in: header
name: X-ACCOUNT
description: All requests must include the `X-ACCOUNT` header containing your account ID.
# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
- accountId: []
或在OpenAPI 3.0中:
openapi: 3.0.0
...
components:
securitySchemes:
accountId:
type: apiKey
in: header
name: X-ACCOUNT
description: All requests must include the `X-ACCOUNT` header containing your account ID.
# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
- accountId: []
paths:
/foo:
# These parameters apply to both GET and POST
parameters:
- $ref: '#/parameters/some_param'
- $ref: '#/parameters/another_param'
get:
...
post:
...
5条答案
按热度按时间vzgqcmou1#
这取决于它们是什么样的参数。
下面的例子是YAML格式的(为了可读性),但是您可以使用http://www.json2yaml.com将它们转换为JSON。
安全相关参数:授权头、API密钥等
用于认证和授权的参数,如
Authorization
头、API key、API密钥对等,应定义为安全方案,而不是参数。在您的示例中,
X-ACCOUNT
看起来像一个API密钥,因此您可以用途:或在OpenAPI 3.0中:
工具处理安全方案参数的方式可能不同于一般参数。例如,Swagger UI不会在操作参数中列出API密钥;相反,它将显示“授权”按钮,您的用户可以在其中输入他们的API密钥。
通用参数:偏移、限制、资源ID等。
OpenAPI 2.0和3.0没有全局参数的概念。有现有的功能请求:
Allow for responses and parameters shared across all endpoints
Group multiple parameter definitions for better maintainability
你最多只能在全局
parameters
部分(在OpenAPI 2.0中)或components/parameters
部分(在OpenAPI 3.0中)定义这些参数,然后在每个操作中显式地$ref
所有参数。缺点是你需要在每个操作中复制$ref
。为了在一定程度上减少代码重复,可以在路径级别而不是在操作内部定义适用于路径上所有操作的参数。
rks48beu2#
如果是消费者调用API时发送的头参数...
你至少可以在parameters部分一次性定义它们,然后只在需要的时候引用它们。在下面的例子中:
CommonPathParameterHeader
、ReusableParameterHeader
和AnotherReusableParameterHeader
是在文档根目录的parameters
中一次性定义的,可用于任何参数列表CommonPathParameterHeader
在/resources
和/other-resources
路径的parameters
部分中引用,这意味着这些路径的所有操作都需要此标头get /resources
中引用了ReusableParameterHeader
,这意味着此操作需要它get /other-resources
中的AnotherReusableParameterHeader
也是如此示例:
如果你说的是每个API响应发送的header ...
不幸的是,你不能定义可重用的响应头,但至少你可以为常见的HTTP响应(如500错误)定义一个包含这些头的可重用响应。
示例:
关于OpenAPI(fka.Swagger)下一版本
OpenAPI规范(fka.Swagger)将不断发展,并包括可重用响应头的定义(参见https://github.com/OAI/OpenAPI-Specification/issues/563)。
pkwftd7m3#
根据这个Swagger问题评论,在可预见的未来不计划支持全局参数(包括头参数),但为了限制重复,您应该使用参数引用,如@Arnaud的答案(
parameters: - $ref: '#/parameters/paramX'
)。zvms9eto4#
在OpenAPI 3.1下:
yvgpqqbh5#
还希望有一些全局变量,可以在任何地方使用.
(甚至在一些示例中,因此可以在UI中全局地改变公共设置)。
类似于shell或javascript中的
"hello ${var1}"
。多次搜索文档,尚未找到解决方案。
:(