OpenAPI中如何定义全局参数？

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

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

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

这到底有可能吗？

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

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

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

用于认证和授权的参数，例如Authorization标头，API key https://stackoverflow.com/q/1453073/113116、 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没有全局参数的概念。现有的功能请求：
允许在所有端点之间共享响应和参数 https://github.com/OAI/OpenAPI-Specification/issues/1577
将多个参数定义分组以获得更好的可维护性 https://github.com/OAI/OpenAPI-Specification/issues/445

您最多能做的就是在全局中定义这些参数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:
      ...