swagger 如何在OpenAPI中定义全局参数?

kqlmhetl  于 2023-04-06  发布在  其他
关注(0)|答案(5)|浏览(502)

我正在准备我的API文档,通过手工操作而不是自动生成。我有应该发送给所有API的标题,不知道是否可以为整个API全局定义参数?
其中一些头是静态的,有些必须在调用API时设置,但它们在所有API中都是相同的,我不想为每个API和每个方法复制和粘贴参数,因为这在未来将无法维护。
我看到了API定义的静态头文件,但没有一个单独的文档说明如何设置或使用它们。
这到底有没有可能?

vzgqcmou

vzgqcmou1#

这取决于它们是什么样的参数。
下面的例子是YAML格式的(为了可读性),但是您可以使用http://www.json2yaml.com将它们转换为JSON。

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

用于认证和授权的参数,如Authorization头、API key、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没有全局参数的概念。有现有的功能请求:
Allow for responses and parameters shared across all endpoints
Group multiple parameter definitions for better maintainability
你最多只能在全局parameters部分(在OpenAPI 2.0中)或components/parameters部分(在OpenAPI 3.0中)定义这些参数,然后在每个操作中显式地$ref所有参数。缺点是你需要在每个操作中复制$ref

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:
      ...
rks48beu

rks48beu2#

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

你至少可以在parameters部分一次性定义它们,然后只在需要的时候引用它们。在下面的例子中:

  • CommonPathParameterHeaderReusableParameterHeaderAnotherReusableParameterHeader是在文档根目录的parameters中一次性定义的,可用于任何参数列表
  • CommonPathParameterHeader/resources/other-resources路径的parameters部分中引用,这意味着这些路径的所有操作都需要此标头
  • 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响应发送的header ...

不幸的是,你不能定义可重用的响应头,但至少你可以为常见的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)。

pkwftd7m

pkwftd7m3#

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

zvms9eto

zvms9eto4#

在OpenAPI 3.1下:

openapi: 3.1.0

paths:
  /users:
    parameters:
      - $ref: '#/components/parameters/common-parameter'
    get:
      ...

  /organizations: 
    parameters:
      - $ref: '#/components/parameters/common-parameter'
    get:
      ...

components:
  parameters:
    common-parameter:
      in: query
      name: common-parameter
      schema:
        type: integer
        minimum: 0
yvgpqqbh

yvgpqqbh5#

还希望有一些全局变量,可以在任何地方使用.
(甚至在一些示例中,因此可以在UI中全局地改变公共设置)。
类似于shell或javascript中的"hello ${var1}"
多次搜索文档,尚未找到解决方案。
:(

相关问题