定义全局参数

Question

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

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

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

这有可能吗？

Answer 1

如果你在谈论消费者在调用API时发送的标题参数：

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

• CommonPathParameterHeader，ReusableParameterHeader和AnotherReusableParameterHeader在文档根目录parameters中一劳永逸地定义，可以在任何参数列表中使用
{li> CommonPathParameterHeader在parameters和/resources路径的/other-resources部分中被引用，这意味着这些路径的所有操作都需要此标题 {li> 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响应发送的标头 遗憾的是，您无法定义可重用的响应标头。 但至少你可以定义包含这些标题的可重用响应，例如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

根据this Swagger issue comment，在可预见的将来不会计划对全局参数（包括标头参数）的支持，但为了限制重复，您应该使用参数引用，如@Arnaud's answer {{1} }）。