跳过内容

描述参数

在 OpenAPI 3.0 中，参数在操作或路径的 parameters 部分定义。要描述一个参数，您需要指定其 name、位置 (in)、数据类型（由 schema 或 content 定义）以及其他属性，例如 description 或 required。示例如下

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Get a user by ID
5
      parameters:
6
        - in: path
7
          name: userId
8
          schema:
9
            type: integer
10
          required: true
11
          description: Numeric ID of the user to get

请注意，parameters 是一个数组，因此在 YAML 中，每个参数定义都必须在其前面带一个短划线 (-)。

参数类型

OpenAPI 3.0 根据参数位置区分以下参数类型。位置由参数的 in 键确定，例如 in: query 或 in: path。

路径参数

路径参数是 URL 路径的可变部分。它们通常用于指向集合中的特定资源，例如通过 ID 标识的用户。一个 URL 可以有多个路径参数，每个参数都用大括号 { } 表示。

1
GET /users/{id}
2
GET /cars/{carId}/drivers/{driverId}
3
GET /report.{format}

当客户端进行 API 调用时，每个路径参数都必须替换为实际值。在 OpenAPI 中，路径参数使用 in: path 定义。参数名称必须与路径中指定的名称相同。另外请记住添加 required: true，因为路径参数总是必需的。例如，/users/{id} 端点将描述为

1
paths:
2
  /users/{id}:
3
    get:
4
      parameters:
5
        - in: path
6
          name: id # Note the name is the same as in the path
7
          required: true
8
          schema:
9
            type: integer
10
            minimum: 1
11
          description: The user ID

包含数组和对象的路径参数可以通过不同方式序列化

  • 路径风格扩展（矩阵）——以分号为前缀，例如 /map/point;x=50;y=20
  • 标签扩展——以点为前缀，例如 /color.R=100.G=200.B=150
  • 简单风格——以逗号分隔，例如 /users/12,34,56

序列化方法由 style 和 explode 关键字指定。要了解更多信息，请参阅 参数序列化。

查询参数

查询参数是最常见的参数类型。它们出现在请求 URL 的末尾，在问号 (?) 之后，不同的 name=value 对之间用和号 (&) 分隔。查询参数可以是必需的，也可以是可选的。

1
GET /pets/findByStatus?status=available
2
GET /notes?offset=100&limit=50

使用 in: query 表示查询参数

1
parameters:
2
  - in: query
3
    name: offset
4
    schema:
5
      type: integer
6
    description: The number of items to skip before starting to collect the result set
7
  - in: query
8
    name: limit
9
    schema:
10
      type: integer
11
    description: The numbers of items to return

注意：要描述作为查询参数传递的 API 密钥，请改用 securitySchemes 和 security。请参阅 API 密钥。

查询参数可以是原始值、数组和对象。OpenAPI 3.0 提供了多种在查询字符串中序列化对象和数组的方法。

数组可以序列化为

  • form – /products?color=blue,green,red 或 /products?color=blue&color=green，取决于 explode 关键字
  • spaceDelimited（与 OpenAPI 2.0 中的 collectionFormat: ssv 相同）– /products?color=blue%20green%20red
  • pipeDelimited（与 OpenAPI 2.0 中的 collectionFormat: pipes 相同）– /products?color=blue|green|red

对象可以序列化为

  • form – /points?color=R,100,G,200,B,150 或 /points?R=100&G=200&B=150，取决于 explode 关键字
  • deepObject – /points?color[R]=100&color[G]=200&color[B]=150

序列化方法由 style 和 explode 关键字指定。要了解更多信息，请参阅 参数序列化。

查询参数中的保留字符

RFC 3986 定义了一组保留字符 :/?#[]@!$&'()*+,;=，它们用作 URI 组件分隔符。当这些字符需要在查询参数值中按字面使用时，通常会进行百分比编码。例如，/ 编码为 %2F（或 %2f），因此参数值 quotes/h2g2.txt 将发送为

1
GET /file?path=quotes%2Fh2g2.txt

如果您想要一个未进行百分比编码的查询参数，请在参数定义中添加 allowReserved: true

1
parameters:
2
  - in: query
3
    name: path
4
    required: true
5
    schema:
6
      type: string
7
    allowReserved: true # <-----

在这种情况下，参数值将如下发送

1
GET /file?path=quotes/h2g2.txt

头部参数

API 调用可能要求 HTTP 请求中发送自定义头部。OpenAPI 允许您将自定义请求头部定义为 in: header 参数。例如，假设对 GET /ping 的调用需要 X-Request-ID 头部

1
    GET /ping HTTP/1.1
2
    Host: example.com
3
    X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac

使用 OpenAPI 3.0，您将按如下方式定义此操作

1
paths:
2
  /ping:
3
    get:
4
      summary: Checks if the server is alive
5
      parameters:
6
        - in: header
7
          name: X-Request-ID
8
          schema:
9
            type: string
10
            format: uuid
11
          required: true

类似地，您可以定义自定义响应头。头部参数可以是原始类型、数组和对象。数组和对象使用 simple 样式序列化。有关更多信息，请参阅参数序列化。

注意：不允许使用名为 Accept、Content-Type 和 Authorization 的头部参数。要描述这些头部，请使用相应的 OpenAPI 关键字

头部 OpenAPI 关键字 更多信息请参阅...
Content-Type 请求内容类型：requestBody.content.<media-type>

响应内容类型：responses.<code>.content.<media-type>		 描述请求体,
描述响应,
媒体类型
Accept responses.<code>.content.<media-type> 描述响应,
媒体类型
Authorization securitySchemes, security 认证

操作还可以通过 Cookie 头部传递参数，格式为 Cookie: name=value。多个 Cookie 参数在同一个头部中发送，用分号和空格分隔。

1
GET /api/users
2
Host: example.com
3
Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCUOJ

使用 in: cookie 定义 Cookie 参数

1
parameters:
2
  - in: cookie
3
    name: debug
4
    schema:
5
      type: integer
6
      enum: [0, 1]
7
      default: 0
8
  - in: cookie
9
    name: csrftoken
10
    schema:
11
      type: string

Cookie 参数可以是原始值、数组和对象。数组和对象使用 form 样式序列化。有关更多信息，请参阅 参数序列化。

注意：要定义 Cookie 认证，请改用 API 密钥。

必填和可选参数

默认情况下，OpenAPI 将所有请求参数视为可选。您可以添加 required: true 将参数标记为必需。请注意，路径参数必须具有 required: true，因为它们总是必需的。

1
parameters:
2
  - in: path
3
    name: userId
4
    schema:
5
      type: integer
6
    required: true # <----------
7
    description: Numeric ID of the user to get.

schema 对比 content

要描述参数内容，您可以使用 schema 或 content 关键字。它们是互斥的，用于不同的场景。在大多数情况下，您会使用 schema。它允许您描述原始值，以及序列化为字符串的简单数组和对象。数组和对象参数的序列化方法由该参数中使用的 style 和 explode 关键字定义。

1
parameters:
2
  - in: query
3
    name: color
4
    schema:
5
      type: array
6
      items:
7
        type: string
8


9
    # Serialize as color=blue,black,brown (default)
10
    style: form
11
    explode: false

content 用于 style 和 explode 未涵盖的复杂序列化场景。例如，如果您需要在查询字符串中发送 JSON 字符串，如下所示

1
filter={"type":"t-shirt","color":"blue"}

在这种情况下，您需要将参数 schema 包装到 content/<media-type> 中，如下所示。schema 定义了参数数据结构，而媒体类型（本例中为 application/json）则作为对描述序列化格式的外部规范的引用。

1
parameters:
2
  - in: query
3
    name: filter
4


5
    # Wrap 'schema' into 'content.<media-type>'
6
    content:
7
      application/json: # <---- media type indicates how to serialize / deserialize the parameter content
8
        schema:
9
          type: object
10
          properties:
11
            type:
12
              type: string
13
            color:
14
              type: string

Swagger UI 和 Swagger Editor 用户注意事项：带有 content 的参数在 Swagger UI 3.23.7+ 和 Swagger Editor 3.6.34+ 中受支持。

默认参数值

在参数模式中使用 default 关键字来指定可选参数的默认值。默认值是客户端未在请求中提供参数值时服务器使用的值。值类型必须与参数的数据类型相同。典型的例子是分页参数，例如 offset 和 limit

1
GET /users
2
GET /users?offset=30&limit=10

假设 offset 默认值为 0，limit 默认值为 20，范围在 0 到 100 之间，您将如下定义这些参数

1
parameters:
2
  - in: query
3
    name: offset
4
    schema:
5
      type: integer
6
      minimum: 0
7
      default: 0
8
    required: false
9
    description: The number of items to skip before starting to collect the result set.
10
  - in: query
11
    name: limit
12
    schema:
13
      type: integer
14
      minimum: 1
15
      maximum: 100
16
      default: 20
17
    required: false
18
    description: The number of items to return.

常见错误

使用 default 关键字时有两个常见错误

  • 将 default 与 required 参数或属性一起使用，例如与路径参数一起使用。这没有意义——如果值是必需的，客户端必须始终发送它，并且默认值永远不会被使用。
  • 使用 default 来指定示例值。这不是 default 的预期用途，可能导致某些 Swagger 工具中出现意外行为。请改用 example 或 examples 关键字来实现此目的。请参阅 添加示例。

枚举参数

您可以通过将 enum 添加到参数的 schema 来将参数限制为一组固定的值。枚举值必须与参数数据类型相同。

1
parameters:
2
  - in: query
3
    name: status
4
    schema:
5
      type: string
6
      enum:
7
        - available
8
        - pending
9
        - sold

更多信息：定义枚举。

常量参数

您可以将常量参数定义为只有一个可能值的必需参数

1
parameters:
2
  - in: query
3
    name: rel_date
4
    required: true
5
    schema:
6
      type: string
7
      enum:
8
        - now

enum 属性指定了可能的值。在此示例中，只能使用一个值，这将是 Swagger UI 中用户唯一可选择的值。

注意：常量参数与默认参数值不同。常量参数总是由客户端发送，而默认值是客户端未发送参数时服务器使用的值。

空值和可空参数

查询字符串参数可能只有名称而没有值，如下所示

1
GET /foo?metadata

使用 allowEmptyValue 来描述此类参数

1
parameters:
2
  - in: query
3
    name: metadata
4
    schema:
5
      type: boolean
6
    allowEmptyValue: true # <-----

OpenAPI 3.0 还支持模式中的 nullable，允许操作参数具有 null 值。例如，以下模式对应于 C# 中的 int? 和 Java 中的 java.lang.Integer

1
schema:
2
  type: integer
3
  format: int32
4
  nullable: true

注意：nullable 与可选参数或空值参数不同。nullable 意味着参数值可以是 null。特定的实现可能会选择将缺失或空值参数映射到 null，但严格来说，这些不是同一回事。

参数示例

您可以为参数指定一个 example 或多个 examples。示例值应与参数模式匹配。单个示例

1
parameters:
2
  - in: query
3
    name: limit
4
    schema:
5
      type: integer
6
      minimum: 1
7
    example: 20

多个命名示例

1
parameters:
2
  - in: query
3
    name: ids
4
    description: One or more IDs
5
    required: true
6
    schema:
7
      type: array
8
      items:
9
        type: integer
10
    style: form
11
    explode: false
12
    examples:
13
      oneId:
14
        summary: Example of a single ID
15
        value: [5] # ?ids=5
16
      multipleIds:
17
        summary: Example of multiple IDs
18
        value: [1, 5, 7] # ?ids=1,5,7

详情请参阅添加示例。

弃用参数

使用 deprecated: true 将参数标记为已弃用。

1
- in: query
2
  name: format
3
  required: true
4
  schema:
5
    type: string
6
    enum: [json, xml, yaml]
7
  deprecated: true
8
  description: Deprecated, use the appropriate `Accept` header instead.

通用参数

路径所有方法的通用参数

路径的所有操作共享的参数可以在路径级别定义，而不是在操作级别定义。路径级别参数由该路径的所有操作继承。典型的用例是通过路径参数访问资源进行操作的 GET/PUT/PATCH/DELETE 操作。

1
paths:
2
  /user/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        schema:
7
          type: integer
8
        required: true
9
        description: The user ID
10
    get:
11
      summary: Gets a user by ID
12
      ...
13
    patch:
14
      summary: Updates an existing user with the specified ID
15
      ...
16
    delete:
17
      summary: Deletes the user with the specified ID
18
      ...

操作级别定义的任何额外参数都与路径级别参数一起使用

1
paths:
2
  /users/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        schema:
7
          type: integer
8
        required: true
9
        description: The user ID.
10


11
    # GET/users/{id}?metadata=true
12
    get:
13
      summary: Gets a user by ID
14
      # Note we only define the query parameter, because the {id} is defined at the path level.
15
      parameters:
16
        - in: query
17
          name: metadata
18
          schema:
19
            type: boolean
20
          required: false
21
          description: If true, the endpoint returns only the user metadata.
22
      responses:
23
        "200":
24
          description: OK

特定的路径级别参数可以在操作级别覆盖，但不能删除。

1
paths:
2
  /users/{id}:
3
    parameters:
4
      - in: path
5
        name: id
6
        schema:
7
          type: integer
8
        required: true
9
        description: The user ID.
10


11
    # DELETE /users/{id} - uses a single ID.
12
    # Reuses the {id} parameter definition from the path level.
13
    delete:
14
      summary: Deletes the user with the specified ID.
15
      responses:
16
        "204":
17
          description: User was deleted.
18


19
    # GET /users/id1,id2,id3 - uses one or more user IDs.
20
    # Overrides the path-level {id} parameter.
21
    get:
22
      summary: Gets one or more users by ID.
23
      parameters:
24
        - in: path
25
          name: id
26
          required: true
27
          description: A comma-separated list of user IDs.
28
          schema:
29
            type: array
30
            items:
31
              type: integer
32
            minItems: 1
33
          explode: false
34
          style: simple
35
      responses:
36
        "200":
37
          description: OK

不同路径的通用参数

不同的 API 路径可能具有通用参数，例如分页参数。您可以在全局 components 部分的 parameters 下定义通用参数，并通过 $ref 在其他地方引用它们。

1
components:
2
  parameters:
3
    offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
4
      # Not necessarily the same as the parameter name.
5
      in: query
6
      name: offset
7
      required: false
8
      schema:
9
        type: integer
10
        minimum: 0
11
      description: The number of items to skip before starting to collect the result set.
12
    limitParam:
13
      in: query
14
      name: limit
15
      required: false
16
      schema:
17
        type: integer
18
        minimum: 1
19
        maximum: 50
20
        default: 20
21
      description: The numbers of items to return.
22


23
paths:
24
  /users:
25
    get:
26
      summary: Gets a list of users.
27
      parameters:
28
        - $ref: "#/components/parameters/offsetParam"
29
        - $ref: "#/components/parameters/limitParam"
30
      responses:
31
        "200":
32
          description: OK
33
  /teams:
34
    get:
35
      summary: Gets a list of teams.
36
      parameters:
37
        - $ref: "#/components/parameters/offsetParam"
38
        - $ref: "#/components/parameters/limitParam"
39
      responses:
40
        "200":
41
          description: OK

请注意，components 中定义的参数并非应用于所有操作的参数——它们只是可以轻松重用的全局定义。

参数依赖

OpenAPI 3.0 不支持参数依赖和互斥参数。有一个开放的功能请求位于 https://github.com/OAI/OpenAPI-Specification/issues/256。您可以做的是在参数描述中记录限制，并在 400 Bad Request 响应中定义逻辑。例如，考虑 /report 端点，它接受相对日期范围 (rdate) 或精确范围 (start_date+end_date)

1
GET /report?rdate=Today
2
GET /report?start_date=2016-11-15&end_date=2016-11-20

您可以按如下方式描述此端点

1
paths:
2
  /report:
3
    get:
4
      parameters:
5
        - name: rdate
6
          in: query
7
          schema:
8
            type: string
9
          description: >
10
            A relative date range for the report, such as `Today` or `LastWeek`.
11
            For an exact range, use `start_date` and `end_date` instead.
12
        - name: start_date
13
          in: query
14
          schema:
15
            type: string
16
            format: date
17
          description: >
18
            The start date for the report. Must be used together with `end_date`.
19
            This parameter is incompatible with `rdate`.
20
        - name: end_date
21
          in: query
22
          schema:
23
            type: string
24
            format: date
25
          description: >
26
            The end date for the report. Must be used together with `start_date`.
27
            This parameter is incompatible with `rdate`.
28
      responses:
29
        "400":
30
          description: Either `rdate` or `start_date`+`end_date` are required.

参考

参数对象

没有找到您要找的内容？询问社区
发现错误？告诉我们

© . All rights reserved.