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

Question

我正在通过手动而不是自动生成来准备我的 API 文档。我有应该发送到所有 API 的标头，但不知道是否可以为整个 API 全局定义参数？

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

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

这到底有没有可能？

Answer 1

这取决于它们是什么类型的参数。

以下示例采用 YAML 格式（为了便于阅读），但您可以使用 http://www.json2yaml.com 将它们转换为 JSON。

安全相关参数：授权头、API密钥等

用于身份验证和授权的参数，如Authorization标头、API key、API密钥对等应定义为安全方案而不是参数。

在您的示例中，X-ACCOUNT 看起来像一个 API 密钥，因此您可以使用：

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: []

工具处理安全方案参数的方式可能不同于通用参数。例如，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 所有参数。缺点是每次操作都需要复制$refs。

swagger: "2.0"
...

paths:
  /users:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...
  /organizations:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...

parameters:
  offset:
    in: query
    name: offset
    type: integer
    minimum: 0
  limit:
    in: query
    name: limit
    type: integer
    minimum: 1
    maximum: 50

为了在一定程度上减少代码重复，适用于路径上所有操作的参数可以在路径级别而不是内部操作中定义。

paths:
  /foo:
    # These parameters apply to both GET and POST
    parameters:
      - $ref: '#/parameters/some_param'
      - $ref: '#/parameters/another_param'

    get:
      ...
    post:
      ...

Answer 2

如果您说的是消费者在调用 API 时发送的标头参数...

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

• CommonPathParameterHeader、ReusableParameterHeader 和 AnotherReusableParameterHeader 在文档根目录的 parameters 中一劳永逸地定义，可以在任何参数列表中使用
• CommonPathParameterHeader在/resources和/other-resources路径的parameters部分中被引用，这意味着这些路径的所有操作都需要这个头
• ReusableParameterHeader 在get /resources 中被引用，表示此操作需要它
• AnotherReusableParameterHeader 在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.

如果您说的是随每个 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
          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）将不断发展并包括可重用响应标头的定义（参见https://github.com/OAI/OpenAPI-Specification/issues/563）。

Answer 3

根据this Swagger issue comment，在可预见的将来不计划支持全局参数（包括标头参数），但为了限制重复，您应该使用参数引用，如@Arnaud's 答案（parameters: - $ref: '#/parameters/paramX'）。

Answer 4

还希望一些全局变量，可以在任何地方使用。
（即使在某些示例中，也可以在 ui 中全局更改常用设置）。

类似的东西 "hello ${var1}" 在 shell 或 javascript 中。

多次搜索文档，尚未找到解决方案。
: (