在上一篇文章中，我们了解了 API 的响应内容的格式，也可以说是 API 操作的输出数据。有输出数据，就有输入数据。本文就说一说 API 操作的输入数据。

OpenAPI 提供了两种方式描述输入数据：参数（parameters）和请求体/消息载荷（request body/message payload）。两种参数的作用略有差别。参数常用于识别一类资源；而请求体是对资源内容的描述。

参数对象（Parameter Object）

在 OpenAPI 文档中，Path Item 对象和 Operation 对像都可以保护一个 parameters 字段，该对象是参数对象的一个数组。parameters 字段出现的位置不同，影响也不同。在 Path Item 对象中的 parameters 字段，其内容会被 Path 对象下的所有操作共享；而在 Operation 对象中的 parameters 字段，其内容会覆写 Path Item 对象中 parameters 字段的内容，但不能移除。

每个参数对象都包含下面两个强制字段：

• in（字符串）：参数位置
• name（字符串）：在同一个参数位置，名称必须唯一，且大小写敏感。

还有几个重要的可选字段：

• description（字符串）：参数描述，可以包含使用示例。对于理解文档非常有帮助。
• required（布尔值）：是否必需，默认值是 false.

参数位置

最常见的参数位置，有以下三个：

• path：参数成为操作路径（URL）的一部分，俗称路径参数。

 /users/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true

需要注意的是，路径参数的 required 字段必需为 true.

• query：参数成为操作路径（URL）查询参数的一部分，俗称查询参数，如/users?id=123456：

 /users:
    get:
      parameters:
      - name: id
        in: query

• header：参数成为 HTTP 请求头的一部分，俗称请求头参数。注意：请求头是大小写敏感的。

参数类型

参数类型可以使用 schema 字段进行描述：

parameters:
- name: id
  in: query
  schema:
    type: integer
    minimum: 1
    maximum: 100

请求体对象（Request Body Object）

请求体包含在操作对象中，可以使用 requestBody 字段进行描述，表示为一个请求体对象。在请求体对象中，content 字段是强制字段，描述了请求体的细节。

paths:
  /hello:
    put:
      requestBody:
        content:
          application/json:
            schema:
              type: integer
              minimum: 1
              maximum: 100