Swagger 如何在OpenAPI中定义全局参数？_Swagger_Openapi

Swagger 如何在OpenAPI中定义全局参数？

swagger

Swagger 如何在OpenAPI中定义全局参数？,swagger,openapi,Swagger,Openapi,我正在准备我的API文档，它是按手操作的，而不是自动生成的。我有一些应该发送到所有API的头文件，不知道是否可以为整个API全局定义参数其中有些头是静态的，有些头必须在调用API时设置，但它们在所有API中都是相同的，我不想复制和粘贴每个API和每个方法的参数，因为这在将来是不可维护的我通过API定义看到了静态头，但是没有关于如何设置或使用它们的单独文档这到底有没有可能？根据，在可预见的将来不计划支持全局参数（包括标题参数），但为了限制重复，您应该使用参数引用作为答案（参数：-$ref:“

我正在准备我的API文档，它是按手操作的，而不是自动生成的。我有一些应该发送到所有API的头文件，不知道是否可以为整个API全局定义参数

其中有些头是静态的，有些头必须在调用API时设置，但它们在所有API中都是相同的，我不想复制和粘贴每个API和每个方法的参数，因为这在将来是不可维护的

我通过API定义看到了静态头，但是没有关于如何设置或使用它们的单独文档

这到底有没有可能？

根据，在可预见的将来不计划支持全局参数（包括标题参数），但为了限制重复，您应该使用参数引用作为答案（

参数：-$ref:“#/parameters/paramX”

）.

如果您正在谈论消费者在调用API时发送的头参数…

您至少可以在“参数”部分中一次性定义它们，然后仅在需要时引用它们。在以下示例中：

CommonPathParameterHeader

、

ReusableParameterHeader

和

另一个ReusableParameterHeader

在文档根目录的

parameters

中一次性定义，并可在任何参数列表中使用

```
CommonPathParameterHeader
```
在
```
/resources
```
和
```
/other resources
```
路径的
```
parameters
```
部分中引用，这意味着这些路径的所有操作都需要此头
```
ReusableParameterHeader
```
在
```
get/resources
```
中引用，这意味着此操作需要它
在
```
get/other resources
```

例如：

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
    post:
      responses:
        '204':
          description: Succesfully created.

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
    post:
      responses:
        '204':
          description: Succesfully created.
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
        '500':
          $ref: '#/responses/Standard500ErrorResponse'

responses:
  Standard500ErrorResponse:
    description: An unexpected error occured.
    headers:
      X-Rate-Limit-Remaining:
        type: integer
      X-Rate-Limit-Reset:
        type: string
        format: date-time

如果您谈论的是随每个API响应一起发送的头…

不幸的是，您不能定义可重用的响应头。但至少可以为常见HTTP响应（如500错误）定义包含这些头的可重用响应

例如：

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
    post:
      responses:
        '204':
          description: Succesfully created.

swagger: '2.0'
info:
  version: 1.0.0
  title: Header API
  description: A simple API to learn how you can define headers

parameters:
  CommonPathParameterHeader:
    name: COMMON-PARAMETER-HEADER
    type: string
    in: header
    required: true
  ReusableParameterHeader:
    name: REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true
  AnotherReusableParameterHeader:
    name: ANOTHER-REUSABLE-PARAMETER-HEADER
    type: string
    in: header
    required: true

paths:
  /resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/ReusableParameterHeader'
      responses:
        '200':
          description: gets some resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
  /other-resources:
    parameters:
      - $ref: '#/parameters/CommonPathParameterHeader'
    get:
      parameters:
        - $ref: '#/parameters/AnotherReusableParameterHeader'
      responses:
        '200':
          description: gets some other resources
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
    post:
      responses:
        '204':
          description: Succesfully created.
          headers:
            X-Rate-Limit-Remaining:
              type: integer
            X-Rate-Limit-Reset:
              type: string
              format: date-time
        '500':
          $ref: '#/responses/Standard500ErrorResponse'

responses:
  Standard500ErrorResponse:
    description: An unexpected error occured.
    headers:
      X-Rate-Limit-Remaining:
        type: integer
      X-Rate-Limit-Reset:
        type: string
        format: date-time

关于OpenAPI（fka.Swagger）下一版本

OpenAPI规范（fka.Swagger）将不断发展，其中包括可重用响应头的定义（参见）。这取决于它们是什么类型的参数
下面的示例是YAML（为了可读性），但您可以使用将其转换为JSON
安全相关参数：授权头、API密钥等。用于身份验证和授权的参数，如
授权
头、API密钥对等，应定义为安全方案，而不是参数
在您的示例中，
X-ACCOUNT
看起来像一个API密钥，因此您可以使用：

昂首阔步：“2.0” ... 证券定义：帐号：类型：apiKey 在：标题姓名：X账户说明：所有请求必须包含包含您的帐户ID的“X-ACCOUNT”标题。 #将“X帐户”标头全局应用于所有路径和操作安全： -帐号：[]
或在OpenAPI 3.0中：

openapi:3.0.0 ... 组件：证券计划：帐号：类型：apiKey 在：标题姓名：X账户说明：所有请求必须包含包含您的帐户ID的“X-ACCOUNT”标题。 #将“X帐户”标头全局应用于所有路径和操作安全： -帐号：[]
工具处理安全方案参数的方式可能不同于一般参数。例如，Swagger UI不会在操作参数中列出API键；相反，它将显示“授权”按钮，用户可以在其中输入API密钥
通用参数：偏移量、限制、资源ID等。 OpenAPI 2.0和3.0没有全局参数的概念。存在现有功能请求：

您最多可以在全局
参数
部分（在OpenAPI 2.0中）或
组件/参数
部分（在OpenAPI 3.0中）定义这些参数，然后在每个操作中明确定义所有参数。缺点是您需要在每次操作中复制
$ref
s

昂首阔步：“2.0” ... 路径： /用户：获取：参数： -$ref:“#/parameters/offset” -$ref:“#/parameters/limit” ... /组织：获取：参数： -$ref:“#/parameters/offset” -$ref:“#/parameters/limit” ... 参数：抵消： in:查询名称：偏移量类型：整数最低：0 限制： in:查询名称：限额类型：整数最低限额：1 最高限额：50
为了在某种程度上减少代码重复，可以在路径级别而不是在操作内部定义适用于路径上所有操作的参数

路径： /傅： #这些参数适用于GET和POST 参数： -$ref:“#/parameters/some_param” -$ref:“#/parameters/另一个参数” 获取： ... 职位： ...
您能建议如何在Spring Boot中使用相同的功能吗？