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

Question

我正在通过手工而不是自动生成来准备我的 API 文档。我有应该发送到所有 API 的 header ，但不知道是否可以为整个 API 全局定义参数？
其中一些 header 是静态的，一些必须在调用 API 时设置，但它们在所有 API 中都是相同的，我不想为每个 API 和每个方法复制和粘贴参数，因为这不会将来可维护。
我通过 API 定义看到了静态 header ，但没有关于人们如何设置或使用它们的单一文档。
这可能吗？

Answer 1

如果您在谈论消费者在调用 API 时发送的 header 参数...
您至少可以在参数部分中一劳永逸地定义它们，然后仅在需要时才引用它们。
在下面的例子中:

CommonPathParameterHeader , ReusableParameterHeader和 AnotherReusableParameterHeader在 parameters 中一劳永逸地定义位于文档根目录，可用于任何参数列表

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

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 响应发送的 header ...
不幸的是，您无法定义可重用的响应 header 。
但至少您可以为常见的 HTTP 响应(例如 500 错误)定义包含这些 header 的可重用响应。
例子:

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)将发展并包括可重用响应 header 的定义等(参见 https://github.com/OAI/OpenAPI-Specification/issues/563)。