描述参数

在 Swagger 中，API 操作参数在操作定义的 parameters 部分下定义。每个参数都有 name、值 type（对于原始值参数）或 schema（对于请求正文）以及可选的 description。这是一个示例

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

请注意，parameters 是一个数组，因此，在 YAML 中，每个参数定义都必须在前面列出一个破折号 (-)。

参数类型

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

查询参数，例如 /users?role=admin
路径参数，例如 /users/{id}
标头参数，例如 X-MyHeader: Value
描述 POST、PUT 和 PATCH 请求正文的 body 参数（请参阅描述请求正文）
表单参数 – 用于描述 Content-Type 为 application/x-www-form-urlencoded 和 multipart/form-data 的请求的有效负载的各种 body 参数（后者通常用于文件上传）

查询参数

查询参数是最常见的参数类型。它们出现在请求 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
    type: integer
5
    description: The number of items to skip before starting to collect the result set.
6
  - in: query
7
    name: limit
8
    type: integer
9
    description: The numbers of items to return.

查询参数仅支持原始类型。你可以有一个 array，但 items 必须是原始值类型。不支持对象。

注意：要描述作为查询参数传递的 API 密钥，请使用安全定义代替。请参阅API 密钥。

路径参数

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

1
GET /users/{id}
2
GET /cars/{carId}/drivers/{driverId}

当客户端发出 API 调用时，每个路径参数都必须替换为实际值。在 Swagger 中，使用 in: path 和其他必要的属性定义路径参数。参数名称必须与路径中指定的名称相同。此外，请记住添加 required: true，因为路径参数始终是必需的。这是一个 GET /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
          type: integer
9
          minimum: 1
10
          description: The user ID.
11
        responses:
12
          200:
13
            description: OK

路径参数可以是多值的，例如 GET /users/12,34,56。这是通过将参数类型指定为 array 来实现的。请参阅下面的数组和多值参数。

标头参数

API 调用可能需要在 HTTP 请求中发送自定义标头。Swagger 允许你将自定义请求标头定义为 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

在 Swagger 中，你将按如下方式定义此操作

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
          type: string
9
          required: true

以类似的方式，你可以定义自定义响应标头。

注意：Swagger 规范对于某些标头有特殊的关键字

标头	Swagger 关键字	有关更多信息，请参阅...
`Content-Type`	`consumes`（请求内容类型） `produces`（响应内容类型）	MIME 类型
`Accept`	`produces`	MIME 类型
`Authorization`	`securityDefinitions`、`security`	身份验证

表单参数

表单参数用于描述 Content-Type 为以下内容的请求的有效负载

application/x-www-form-urlencoded（用于 POST 原始值和原始值数组）。
multipart/form-data（用于上传文件或文件和原始数据的组合）。

也就是说，操作的 consumes 属性必须指定这些内容类型之一。表单参数定义为 in: formData。它们只能是原始类型（字符串、数字、布尔值）或原始类型数组（这意味着你不能使用 $ref 作为 items 值）。此外，表单参数不能与 in: body 参数共存，因为 formData 是一种描述正文的特定方式。为了说明表单参数，请考虑一个 HTML POST 表单

1
<form action="http://example.com/survey" method="post">
2
  <input type="text" name="name" />
3
  <input type="number" name="fav_number" />
4
  <input type="submit" />
5
</form>

此表单将数据 POST 到表单的端点

1
POST /survey HTTP/1.1
2
Host: example.com
3
Content-Type: application/x-www-form-urlencoded
4
Content-Length: 29
5

6
name=Amy+Smith&fav_number=321

在 Swagger 中，你可以按如下方式描述端点

1
paths:
2
  /survey:
3
    post:
4
      summary: A sample survey.
5
      consumes:
6
        - application/x-www-form-urlencoded
7
      parameters:
8
        - in: formData
9
          name: name
10
          type: string
11
          description: A person's name.
12
        - in: formData
13
          name: fav_number
14
          type: number
15
          description: A person's favorite number.
16
      responses:
17
        200:
18
          description: OK

要了解如何定义用于文件上传的表单参数，请参阅文件上传。

必需和可选参数

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

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

默认参数值

你可以使用 default 键来为可选参数指定默认值。默认值是如果客户端未在请求中提供参数值，服务器将使用的值。值类型必须与参数的数据类型相同。一个典型的例子是分页参数，如偏移量和限制

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

假设偏移量默认为 0，限制默认为 20，范围从 0 到 100，你将按如下方式定义这些参数

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

常见错误

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

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

枚举参数

enum 关键字允许您将参数值限制为一组固定的值。枚举值必须与参数 type 的类型相同。

1
- in: query
2
  name: status
3
  type: string
4
  enum: [available, pending, sold]

更多信息：定义枚举。

数组和多值参数

路径、查询、标头和表单参数可以接受值列表，例如

1
GET /users/12,34,56,78
2
GET /resource?param=value1,value2,value3
3
GET /resource?param=value1&param=value2&param=value3
4

5
POST /resource
6
param=value1&param=value2

多值参数必须使用 type: array 和适当的 collectionFormat 进行定义。

1
# color=red,black,white
2
parameters:
3
  - in: query
4
    name: color
5
    type: array
6
    collectionFormat: csv
7
    items:
8
      type: string

collectionFormat 指定数组格式（具有多个参数的单个参数或具有相同名称的多个参数）以及数组项的分隔符。

collectionFormat	描述	示例
`csv` (默认)	逗号分隔值。	`foo,bar,baz`
`ssv`	空格分隔值。	`foo bar baz`
`tsv`	制表符分隔值。	`"foo\tbar\tbaz"`
`pipes`	管道分隔值。	`foo\|bar\|baz`
`multi`	多个参数实例，而不是多个值。这仅支持用于 `in: query` 和 `in: formData` 参数。	`foo=value&foo=another_value`

此外，您可以

使用 minItems 和 maxItems 来控制数组的大小，
强制 uniqueItems，
将数组项限制为一组固定的 enum 值。

例如

1
- in: query
2
  name: color
3
  required: false
4
  type: array
5
  minItems: 1
6
  maxItems: 5
7
  uniqueItems: true
8
  items:
9
    type: string
10
    enum:
11
      [
12
        black,
13
        white,
14
        gray,
15
        red,
16
        pink,
17
        orange,
18
        yellow,
19
        green,
20
        blue,
21
        purple,
22
        brown,
23
      ]

您还可以指定如果省略此参数，服务器将使用的默认数组

1
- in: query
2
  name: sort
3
  required: false
4
  type: array
5
  items:
6
    type: string
7
  default: ["-modified", "+id"]

常量参数

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

1
- required: true
2
  enum: [value]

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

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

没有值的参数

查询字符串和表单数据参数可能只有名称，而没有值

1
GET /foo?metadata
2

3
POST /something
4
foo&bar&baz

使用 allowEmptyValue 来描述此类参数

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

公共参数

路径所有方法的通用参数

参数可以在路径本身下定义，在这种情况下，参数存在于此路径下描述的所有操作中。一个典型的例子是操纵通过路径参数访问的相同资源的 GET/PUT/PATCH/DELETE 操作。

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

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
        type: integer
7
        required: true
8
        description: The user ID.
9

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

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

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

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

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

不同路径中的通用参数

不同的 API 路径可能有一些通用参数，例如分页参数。您可以在全局 parameters 部分中定义通用参数，并通过 $ref 在单个操作中引用它们。

1
parameters:
2
  offsetParam: # <-- Arbitrary name for the definition that will be used to refer to it.
3
    # Not necessarily the same as the parameter name.
4
    in: query
5
    name: offset
6
    required: false
7
    type: integer
8
    minimum: 0
9
    description: The number of items to skip before starting to collect the result set.
10
  limitParam:
11
    in: query
12
    name: limit
13
    required: false
14
    type: integer
15
    minimum: 1
16
    maximum: 50
17
    default: 20
18
    description: The numbers of items to return.
19
paths:
20
  /users:
21
    get:
22
      summary: Gets a list of users.
23
      parameters:
24
        - $ref: "#/parameters/offsetParam"
25
        - $ref: "#/parameters/limitParam"
26
      responses:
27
        200:
28
          description: OK
29
  /teams:
30
    get:
31
      summary: Gets a list of teams.
32
      parameters:
33
        - $ref: "#/parameters/offsetParam"
34
        - $ref: "#/parameters/limitParam"
35
      responses:
36
        200:
37
          description: OK

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

参数依赖关系

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

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
          type: string
8
          description: >
9
            A relative date range for the report, such as `Today` or `LastWeek`.
10
            For an exact range, use `start_date` and `end_date` instead.
11
        - name: start_date
12
          in: query
13
          type: string
14
          format: date
15
          description: >
16
            The start date for the report. Must be used together with `end_date`.
17
            This parameter is incompatible with `rdate`.
18
        - name: end_date
19
          in: query
20
          type: string
21
          format: date
22
          description: >
23
            The end date for the report. Must be used together with `start_date`.
24
            This parameter is incompatible with `rdate`.
25
      responses:
26
        400:
27
          description: Either `rdate` or `start_date`+`end_date` are required.

常见问题解答

何时应该使用“type”与“schema”？

schema 仅用于 in: body 参数。任何其他参数都期望原始类型，例如 type: string 或原始类型的 array。

我可以将对象作为查询参数吗？

这在 OpenAPI 3.0 中是可能的，但在 2.0 中不行。

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