OAS 2 此页面适用于 OpenAPI 规范版本 2（以前的 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面.

描述参数

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

paths:
  /users/{userId}:
    get:
      summary: Gets a user by ID.
      parameters:
        - in: path
          name: userId
          type: integer
          required: true
          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 请求主体的正文参数（请参阅 描述请求主体）
• 表单参数 – 用于描述 Content-Type 为 application/x-www-form-urlencoded 和 multipart/form-data 的请求有效负载的各种正文参数（后者通常用于 文件上传）

查询参数

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

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

使用 in: query 表示查询参数

     parameters:
        - in: query
          name: offset
          type: integer
          description: The number of items to skip before starting to collect the result set.
        - in: query
          name: limit
          type: integer
          description: The numbers of items to return.

查询参数只支持基本类型。您可能有一个 array，但 items 必须是基本值类型。不支持对象。

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

路径参数

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

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

当客户端进行 API 调用时，每个路径参数都必须用实际值替换。在 Swagger 中，路径参数使用 in: path 和其他必要的属性定义。参数名称必须与路径中指定的名称相同。此外，请记住添加 required: true，因为路径参数始终是必需的。以下是以 GET /users/{id} 为例

paths:
  /users/{id}:
    get:
      parameters:
        - in: path
          name: id   # Note the name is the same as in the path
          required: true
          type: integer
          minimum: 1
          description: The user ID.
       responses:
         200:
           description: OK

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

标头参数

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

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

在 Swagger 中，您可以按如下方式定义此操作

paths:
  /ping:
    get:
      summary: Checks if the server is alive.
      parameters:
        - in: header
          name: X-Request-ID
          type: string
          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 表单

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

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

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

name=Amy+Smith&fav_number=321

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

paths:
  /survey:
    post:
      summary: A sample survey.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - in: formData
          name: name
          type: string
          description: A person's name.
        - in: formData
          name: fav_number
          type: number
          description: A person's favorite number.
      responses:
        200:
          description: OK

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

必需参数和可选参数

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

      parameters:
        - in: path
          name: userId
          type: integer
          required: true    # <----------
          description: Numeric ID of the user to get.

默认参数值

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

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

假设 offset 默认值为 0，limit 默认值为 20，并且范围为 0 到 100，您将按如下方式定义这些参数

      parameters:
        - in: query
          name: offset
          type: integer
          required: false
          default: 0
          minimum: 0
          description: The number of items to skip before starting to collect the result set.
        - in: query
          name: limit
          type: integer
          required: false
          default: 20
          minimum: 1
          maximum: 100
          description: The numbers of items to return.

常见错误

在使用 default 关键字时，有两种常见的错误

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

枚举参数

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

        - in: query
          name: status
          type: string
          enum: [available, pending, sold]

更多信息：定义枚举。

数组和多值参数

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

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

POST /resource
param=value1&param=value2

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

      # color=red,black,white
      parameters:
        - in: query
          name: color
          type: array
          collectionFormat: csv
          items:
            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 值。

例如

        - in: query
          name: color
          required: false
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          items:
            type: string
            enum: [black, white, gray, red, pink, orange, yellow, green, blue, purple, brown]

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

        - in: query
          name: sort
          required: false
          type: array
          items:
            type: string
          default: ["-modified", "+id"]

常量参数

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

- required: true
  enum: [value]

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

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

没有值的参数

查询字符串和表单数据参数可能只包含名称，不包含值

GET /foo?metadata

POST /something
foo&bar&baz

使用 allowEmptyValue 描述此类参数

        - in: query
          name: metadata
          required: true
          type: boolean
          allowEmptyValue: true  # <-----

常用参数

所有路径方法的常用参数

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

paths:
  /user/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

    get:
      summary: Gets a user by ID.
      ...
    patch:
      summary: Updates an existing user with the specified ID.
      ...
    delete:
      summary: Deletes the user with the specified ID.
      ...

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

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

    # GET/users/{id}?metadata=true
    get:
      summary: Gets a user by ID.
      # Note we only define the query parameter, because the {id} is defined at the path level.
      parameters:
        - in: query
          name: metadata
          type: boolean
          required: false
          description: If true, the endpoint returns only the user metadata.
      responses:
        200:
          description: OK

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

paths:
  /users/{id}:
    parameters:
      - in: path
        name: id
        type: integer
        required: true
        description: The user ID.

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

    # GET /users/id1,id2,id3 - uses one or more user IDs.
    # Overrides the path-level {id} parameter.
    get:
      summary: Gets one or more users by ID.
      parameters:
        - in: path
          name: id
          required: true
          description: A comma-separated list of user IDs.
          type: array
          items:
            type: integer
          collectionFormat: csv
          minItems: 1
      responses:
        200:
          description: OK

不同路径的公共参数

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

parameters:
  offsetParam:  # <-- Arbitrary name for the definition that will be used to refer to it.
                # Not necessarily the same as the parameter name.
    in: query
    name: offset
    required: false
    type: integer
    minimum: 0
    description: The number of items to skip before starting to collect the result set.
  limitParam:
    in: query
    name: limit
    required: false
    type: integer
    minimum: 1
    maximum: 50
    default: 20
    description: The numbers of items to return.
paths:
  /users:
    get:
      summary: Gets a list of users.
      parameters:
        - $ref: '#/parameters/offsetParam'
        - $ref: '#/parameters/limitParam'
      responses:
        200:
          description: OK
  /teams:
    get:
      summary: Gets a list of teams.
      parameters:
        - $ref: '#/parameters/offsetParam'
        - $ref: '#/parameters/limitParam'
      responses:
        200:
          description: OK

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

参数依赖关系

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

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

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

paths:
  /report:
    get:
      parameters:
        - name: rdate
          in: query
          type: string
          description: >
             A relative date range for the report, such as `Today` or `LastWeek`.
             For an exact range, use `start_date` and `end_date` instead.
        - name: start_date
          in: query
          type: string
          format: date
          description: >
            The start date for the report. Must be used together with `end_date`.
            This parameter is incompatible with `rdate`.
        - name: end_date
          in: query
          type: string
          format: date
          description: >
            The end date for the report. Must be used together with `start_date`.
            This parameter is incompatible with `rdate`.
      responses:
        400:
          description: Either `rdate` or `start_date`+`end_date` are required.

常见问题解答

我什么时候应该使用 "type" 与 "schema"？

schema 仅与 in: body 参数一起使用。 任何其他参数都希望一个基本类型，例如 type: string 或基本类型的 array。

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

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

  

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