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

Question

我准备我的API文档的方式是每只手做一次，而不是自动生成。我有应该发送到所有API的头，不知道是否可以为整个API全局定义参数？

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

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

这到底有没有可能？

Answer 1

如果您讨论的是使用者在调用API时发送的头参数...

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

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

如果您说的是与每个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