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

Question

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

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

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

这到底是不是可能呢？

Answer 1

如果您谈论的是消费者在调用时发送的头参数...

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

• CommonPathParameterHeader，ReusableParameterHeader和AnotherReusableParameterHeader是在文档根目录的parameters中一次性定义的，并且可以在parameters和/resources路径的/other-resources部分中引用的任何参数中使用，这意味着这些路径的所有操作都需要在get /resources中引用此header
• ReusableParameterHeader，这意味着在get /other-resources

中的这个/other-resources thing get /resources AnotherReusableParameterHeader中需要它

示例：

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.

如果您谈论的是与每个响应一起发送的报头...

不幸的是，您不能定义可重用的响应头。但至少您可以为常见的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 2

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

下面的示例是YAML (为了可读性)，但您可以使用http://www.json2yaml.com将它们转换为JSON。

安全相关参数: Authorization头部、API密钥等。

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

在您的示例中，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密钥；相反，它会显示"Authorize“按钮，您的用户可以在该按钮中输入他们的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。

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 3

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