定义全局参数

时间:2013-10-25 12:42:42

标签: swagger

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

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

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

这有可能吗?

2 个答案:

答案 0 :(得分:23)

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

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

  • CommonPathParameterHeaderReusableParameterHeaderAnotherReusableParameterHeader在文档根目录parameters中一劳永逸地定义,可以在任何参数列表中使用
  • {li> CommonPathParameterHeaderparameters/resources路径的/other-resources部分中被引用,这意味着这些路径的所有操作都需要此标题 {li> ReusableParameterHeaderget /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)。

答案 1 :(得分:3)

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