openapi回调地址请求不通过_OpenAPI规范（6）—描述参数

在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=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定义了一组保留字符：/?#[]@!$&'()*+,;=，这些字符可以用作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.1Host: example.comX-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方式进行序列化。若要了解更多信息，请参考“参数序列化”。注意：不能使用名为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 # 

模式和内容

若要描述参数内容，你既可以使用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

在style和explode关键字不能覆盖到的复杂的序列化场景中，需要使用content关键字。例如，如果你需要在查询字符串中发送JSON字符串，如下所示：

filter={"type":"t-shirt