OpenAPI规范（6）—描写参数

在OpenAPI 3.0中，参数在操作或路径的parameters分段中定义。若要描写一个参数，你需要指定它的名称（name）、位置（in）、数据类型（由schema或content定义）以及其他属性（例如：description或required）。下面是一个示例：

paths: /users/{userId}: get: su妹妹ary: Get a user by ID parameters: - in: path name: userId schema: type: integer required: true description: Numeric ID of the user to get文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

注意，示例中的parameters是一个数组。因而，在YAML中，每一个参数定义必须在它前面用短划线（-）列出。文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

参数类型文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

OpenAPI 3.0可以依据参数位置区别下列参数类型。参数位置由参数的in关键字来肯定，例如：in: query或in: path。文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

路径参数，例如：/users/{id}文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

查询参数，例如：/users?role=admin文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

标头参数，例如：X-MyHeader: Value文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

cookie参数，通过Cookie标头进行传递，例如：Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

路径参数文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

路径参数是URL路径的可变部份。通常，它们用于指向聚拢中的某个特定资源（例如：由ID标识的用户）。URL可以包括多个路径参数，每一个参数用花括号{ }表示。文章源自微观生活（93wg.com）微观生活-https://93wg.com/17051.html

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

路径式的扩大（矩阵）— 以分号为前缀，例如：/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=availableGET /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定义了一组保存字符：/?

GET /file?path=quotes%2Fh2g2.txtGET /ping HTTP/1.1Host: example.comX-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac

使用OpenAPI 3.0，你可以将这个操作定义成：

paths: /ping: get: su妹妹ary: Checks if the server is alive parameters: - in: header name: X-Request-ID schema: type: string format: uuid required: true

以相似的方式，你可以定义自定义的响应标头。标头参数可以是原始类型、数组以及对象。数组以及对象可使用simple方式进行序列化。若要了解更多信息，请参考“参数序列化”。注意：不能使用名为Accepted、Content-Type以及Authorization的标头参数。若要描写这些标头，请使用相应的OpenAPI关键字：

Cookie参数

操作还可以传递Cookie标头中的参数，例如：Cookie: name=value。可以在同一标头中发送多个cookie参数，以分号以及空格作为分隔符。

GET /api/usersHost: example.comCookie: 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

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

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

在这类情况下，你需要将参数模式包装成content/<media-type>，如下文所示。schema关键字定义了参数的数据结构以及媒体类型（在这个示例中 — application/json），用作对描写序列化格式的外部规范的引用。

parameters: - in: query name: filter​

GET /usersGET /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关键字来指定样本值。这不是默许值的用处，可能会致使某些Swagger工具呈现不可预知的行动。请使用example或examples关键字来实现这类功能（请参考“添加示例”）。

枚举参数

通过将enum添加到参数的schema中，你即可以将参数限制在一个固定的取值规模以内。枚举值必需以及参数的数据类型拥有相同的类型。

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

以上就是微观生活（93wg.com）关于“OpenAPI规范（6）—描写参数”的详细内容，希望对大家有所帮助！