OpenAPI规范（6）—描述参数

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

paths:/users/{userId}:get:summary:GetauserbyIDparameters:-in:pathname:userIdschema:type:integerrequired:truedescription:NumericIDoftheusertoget

注意，示例中的parameters是一个数组。因此，在YAML中，每个参数定义必需在它前面用短划线（-）列出。

可以根据参数位置区分以下参数类型。参数位置由参数的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:pathname:id[]@!amp;'()*+,;=，这些字符可以用作URI分量的分隔符。当这些字符需要在查询参数值中按照字面使用时，它们通常是经过百分号编码的。例如，/被编码成%2F（或%2f）。因此，参数值quotes/将会被发送成：
GET/file?path=quotes%2
如果你想要使某个查询参数不经过百分号编码，那么就要在参数定义中添加allowReserved:true：
parameters:-in:queryname:pathrequired:trueschema:type:stringallowReserved:true----------description:NumericIDoftheusertoget.
模式和内容
若要描述参数内容，你既可以使用schema关键字，也可以使用content关键字。它们是互斥的，可用于不同的场景。在大多数情况下，你将会使用schema关键字。它使得你能够描述原始值，以及序列化成字符串的简单数组和对象。数组和对象参数的序列化方法由该参数中使用的style关键字和explode关键字所定义。
parameters:-in:queryname:colorschema:type:arrayitems:type:stringWrap'schema'into''content:application/json:-----
还支持模式中的nullable关键字，允许操作参数具有null值。例如，以下模式对应于C?ids=5multipleIds:summary:ExampleofmultipleIDsvalue:[1,5,7]GET/users/{id}?metadata=trueget:summary:GetsauserbyIDDELETE/users/{id}-/users/id1,id2,id3-usesoneormoreuserIDs.--Arbitrarynameforthedefinitionthatwillbeusedtorefertoit./components/parameters/offsetParam'-$ref:'/components/parameters/offsetParam'-$ref:'#/components/parameters/limitParam'responses:'200':description:OK

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

不支持参数依赖性和互斥参数。有一个开放性的功能请求，位于：。你可以做的是记录参数描述中的限制，并且在400BadRequest响应中定义逻辑。例如，考虑/report端点，它会接受一个相对的日期范围（rdate）或一个确切的日期范围（start_date+_date）：

GET/report?rdate=TodayGET/report?start_date=2016-11-15_date=2016-11-20

你可以按照如下方式描述这个端点：

paths:/report:get:parameters:-name:rdatein:queryschema:type:stringdescription:Arelativedaterangeforthereport,suchas`Today`or`LastWeek`.Foranexactrange,use`start_date`and`_date`instead.-name:start_datein:queryschema:type:stringformat:datedescription:`_date`.Thisparameterisincompatiblewith`rdate`.-name:_datein:queryschema:type:stringformat:datedescription:`start_date`.Thisparameterisincompatiblewith`rdate`.responses:'400':description:Either`rdate`or`start_date`+`_date`arerequired.

参数对象