29

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

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

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

这可能吗？

4

4 回答 4

24

这取决于它们是什么类型的参数。

下面的示例使用 YAML（为了便于阅读），但您可以使用http://www.json2yaml.com将它们转换为 JSON。

安全相关参数：授权头、API 密钥等。

用于身份验证和授权的参数，例如Authorization标头、API 密钥、API 密钥对等，应定义为安全方案而不是参数。

在您的示例中，X-ACCOUNT看起来像一个 API 密钥，因此您可以使用：

swagger: "2.0"
...

securityDefinitions:
  accountId:
    type: apiKey
    in: header
    name: X-ACCOUNT
    description: All requests must include the `X-ACCOUNT` header containing your account ID.

# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
  - accountId: []

或在 OpenAPI 3.0 中：

openapi: 3.0.0
...

components:
  securitySchemes:
    accountId:
      type: apiKey
      in: header
      name: X-ACCOUNT
      description: All requests must include the `X-ACCOUNT` header containing your account ID.

# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
  - accountId: []

工具可以以不同于通用参数的方式处理安全方案参数。例如，Swagger UI 不会在操作参数中列出 API 键；相反，它将显示“授权”按钮，您的用户可以在其中输入他们的 API 密钥。

通用参数：偏移量、限制、资源 ID 等。

OpenAPI 2.0 和 3.0 没有全局参数的概念。现有功能请求：
允许在所有端点之间共享响应和参数 将
多个参数定义分组以实现更好的可维护性

您最多可以在全局parameters部分（在 OpenAPI 2.0 中）或components/parameters部分（在 OpenAPI 3.0 中）中定义这些参数，然后$ref在每个操作中显式定义所有参数。缺点是您需要$ref在每个操作中复制 s。

swagger: "2.0"
...

paths:
  /users:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...
  /organizations:
    get:
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      ...

parameters:
  offset:
    in: query
    name: offset
    type: integer
    minimum: 0
  limit:
    in: query
    name: limit
    type: integer
    minimum: 1
    maximum: 50

为了在一定程度上减少代码重复，可以在路径级别而不是内部操作中定义适用于路径上所有操作的参数。

paths:
  /foo:
    # These parameters apply to both GET and POST
    parameters:
      - $ref: '#/parameters/some_param'
      - $ref: '#/parameters/another_param'

    get:
      ...
    post:
      ...
于 2017-05-29T19:57:12.557 回答
23

如果您谈论的是消费者在调用 API 时发送的标头参数...

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

  • CommonPathParameterHeader,ReusableParameterHeader并且在文档的根目录中AnotherReusableParameterHeader一劳永逸地定义parameters并且可以在任何参数列表中使用
  • CommonPathParameterHeader在和pathsparameters部分引用，意味着这些paths的ALL操作都需要这个header/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 响应一起发送的标头...

不幸的是，您无法定义可重用的响应标头。但至少您可以为常见的 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

关于 OpenAPI (fka. Swagger) 下一个版本

OpenAPI 规范（fka. Swagger）将不断发展并包括可重用响应标头的定义（参见https://github.com/OAI/OpenAPI-Specification/issues/563）。

于 2016-05-16T12:50:02.600 回答
4

根据这个 Swagger 问题评论，在可预见的将来没有计划对全局参数（包括标头参数）的支持，但为了限制重复，您应该使用参数引用，如@Arnaud 的答案（parameters: - $ref: '#/parameters/paramX'）。

于 2015-12-07T12:35:14.547 回答
-1

也希望一些全局变量，可以在任何地方使用。
（即使在某些示例中，也可以在 ui 中全局更改常用设置）。

类似于 "hello ${var1}"shell 或 javascript 的东西。


多次搜索文档，尚未找到解决方案。
: (

于 2022-01-31T14:35:38.203 回答