如何在 OpenAPI 中定义全局参数? [英] How to define global parameters in OpenAPI?

问题描述

我正在准备我的 API 文档，方法是手工制作而不是自动生成.我有一些应该发送到所有 API 的标头，但不知道是否可以为整个 API 全局定义参数?

I'm preparing my API documentation by doing it per hand and not auto generated. There I have headers that should be sent to all APIs and don't know if it is possible to define parameters globally for the whole API or not?

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

Some of these headers are static and some has to be set when call to API is made, but they are all the same in all APIs, I don't want to copy and paste parameters for each API and each method as this will not be maintainable in the future.

我看到了 API 定义的静态标头，但没有关于如何设置或使用它们的单一文档.

I saw the static headers by API definition but there is no single document for how somebody can set them or use them.

这可能吗?

推荐答案

如果你说的是消费者在调用 API 时发送的头参数...

您至少可以在参数部分中定义它们一劳永逸，然后仅在需要时引用它们.在下面的例子中:

You can at least define them once and for all in parameters sections then only reference them when needed. In the example below:

• CommonPathParameterHeader、ReusableParameterHeader 和 AnotherReusableParameterHeader 在文档根目录的 parameters 中一次性定义并且可以在任何参数列表中使用
• CommonPathParameterHeader 在 /resources 和 /other-resources 路径的 parameters 部分中被引用，这意味着所有这些路径的操作需要这个头
• ReusableParameterHeader 在 get/resources 中被引用，意味着这个操作需要它
• 对于 get/other-resources
中的 AnotherReusableParameterHeader 也是一样的

• CommonPathParameterHeader, ReusableParameterHeader and AnotherReusableParameterHeader are defined once and for all in parameterson the root of the document and can be used in any parameters list
• CommonPathParameterHeaderis referenced in parameters section of /resources and /other-resources paths, meaning that ALL operation of these paths need this header
• ReusableParameterHeader is referenced in get /resources meaning that it's needed on this operation
• Same thing for AnotherReusableParameterHeader in 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 响应发送的标头...

很遗憾，您无法定义可重用的响应标头.但至少您可以为常见的 HTTP 响应(例如 500 错误)定义包含这些标头的可重用响应.

Unfortunately you cannot define reusable response headers. But at least you can define a reusable response containing these headers for common HTTP responses such as a 500 error.

示例:

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).

The OpenAPI spec (fka. Swagger) will evolve and include the definition of reusable response headers among other things (cf. https://github.com/OAI/OpenAPI-Specification/issues/563).

这篇关于如何在 OpenAPI 中定义全局参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！