OAS 3 此页面介绍的是 OpenAPI 3.0。如果您使用的是 OpenAPI 2.0，请参阅我们的 OpenAPI 2.0 指南。

参数描述

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

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get

请注意，parameters 是一个数组，因此在 YAML 中，每个参数定义必须在其前面列出一个连字符 (-)。

参数类型

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

• 路径参数，例如 /users/{id}
• 查询参数，例如 /users?role=admin
• 标头参数，例如 X-MyHeader: Value
• Cookie 参数，它们通过 Cookie 标头传递，例如 Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU

路径参数

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

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

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

paths:
  /users/{id}:
    get:
      parameters:
        - in: path
          name: id   # Note the name is the same as in the path
          required: true
          schema:
            type: integer
            minimum: 1
          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 对用取号 (&) 分隔。查询参数可以是必需的，也可以是可选的。

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

使用 in: query 来表示查询参数

     parameters:
        - in: query
          name: offset
          schema:
            type: integer
          description: The number of items to skip before starting to collect the result set
        - in: query
          name: limit
          schema:
            type: integer
          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 将发送为

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

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

      parameters:
        - in: query
          name: path
          required: true
          schema:
            type: string
          allowReserved: true    # <-----

在这种情况下，参数值将按以下方式发送

GET /file?path=quotes/h2g2.txt

标头参数

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

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

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

paths:
  /ping:
    get:
      summary: Checks if the server is alive
      parameters:
        - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          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 标头中传递参数，例如 Cookie: name=value。多个 Cookie 参数在同一标头中发送，用分号和空格分隔。

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

使用 in: cookie 来定义 Cookie 参数

      parameters:
        - in: cookie
          name: debug
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - in: cookie
          name: csrftoken
          schema:
            type: string

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

注意：要定义 Cookie 身份验证，请使用 API 密钥。

必需参数和可选参数

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

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

schema 与 content

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

parameters:
  - in: query
    name: color
    schema:
      type: array
      items:
        type: string

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

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

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

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

parameters:
  - in: query
    name: filter
	
    # Wrap 'schema' into 'content.<media-type>'
    content:
      application/json:  # <---- media type indicates how to serialize / deserialize the parameter content

        schema:
          type: object
          properties:
            type:
              type: string
            color:
              type: string

注意适用于 Swagger UI 和 Swagger Editor 用户：具有 content 的参数在 Swagger UI 3.23.7+ 和 Swagger Editor 3.6.34+ 中受支持。

默认参数值

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

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

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

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

常见错误

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

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

枚举参数

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

      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum:
              - available
              - pending
              - sold

更多信息：定义枚举。

常量参数

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

      parameters:
        - in: query
          name: rel_date
          required: true
          schema:
            type: string
            enum:
              - now

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

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

空值参数和可空参数

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

GET /foo?metadata

使用allowEmptyValue来描述此类参数

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

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

          schema:
            type: integer
            format: int32
            nullable: true

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

参数示例

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

      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
          example: 20

多个命名示例

      parameters:
        - in: query
          name: ids
          description: One or more IDs
          required: true
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: false
          examples:
            oneId:
              summary: Example of a single ID
              value: [5]   # ?ids=5
            multipleIds:
              summary: Example of multiple IDs
              value: [1, 5, 7]   # ?ids=1,5,7

有关详细信息，请参阅添加示例。

已弃用的参数

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

        - in: query
          name: format
          required: true
          schema:
            type: string
            enum: [json, xml, yaml]
          deprecated: true
          description: Deprecated, use the appropriate `Accept` header instead.

通用参数

所有方法的通用参数

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

paths:
  /user/{id}:
    parameters:
      - in: path
        name: id
        schema:
          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
        schema:
          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
          schema:
            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
        schema:
          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.
          schema:
            type: array
            items:
              type: integer
            minItems: 1
          explode: false
          style: simple
      responses:
        '200':
          description: OK

各种路径的通用参数

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

components:
  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
      schema:
        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
      schema:
        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: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
  /teams:
    get:
      summary: Gets a list of teams.
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK

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

参数依赖

OpenAPI 3.0 不支持参数依赖和互斥参数。在https://github.com/OAI/OpenAPI-Specification/issues/256有一个开放的功能请求。您可以做的是在参数描述中记录限制，并在400 Bad Request响应中定义逻辑。例如，考虑接受相对日期范围(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
          schema:
            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
          schema:
            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
          schema:
            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.

参考

参数对象

  

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