API 入门 (30) 使用 OpenAPI 描述 REST A

我们在前面的一篇文章中，介绍了了如何描述 API 的查询参数。本文将继续介绍如何描述另一种请求参数——请求体参数。

我们已经知道，查询参数是放置在 URL 路径中，如下面代码所示：

http://www.topeid.com/bikes?key={value}

请求体参数则是放置在 HTTP 对请求体中，如下面代码所示：

POST /bikes HTTP/1.1
Accept: application/json
Host:

{
    name: "赤兔",
    price: 1999.99,
    weight: 6.18,
    description: "这是一辆速度感十足的自行车。"
}

当然，我们也可以把请求体参数的数据，通过查询参数的方式进行发送。但是，这样做会有两个问题：一是，如果查询参数过多，导致 URL 过长，可能会受 URL 长度限制，无法传递更多数据；二是，在服务端接收数据时，处理参数赋值和验证会比较繁琐。

接下来，我们就使用 OpenAPI 对请求体参数进行描述。

添加自行车

在添加自行车时，用户会提供名称，价格，重量和描述等信息。用户录入的这些信息，通过请求体参数，发送给后端服务。

首先，我们需要为自行车资源增加一个操作 post，表示创建自行车资源。同时，为 post 操作添加了文档描述。

  /bikes:
    post:
      summary: 添加自行车。
      description: 添加自行车到目录中。

然后，我们添加 requestBody 属性，并使用 description 属性对请求体对数据进行说明。application/json 属性定义了请求体所包含数据对格式，JSON. schema 属性对数据格式进行详细定义。

...
    description: 添加自行车到目录中。
    requestBody:
      description: 自行车信息。
      content:
        application/json:
          schema:
          [...]

最后，我们再来看看 schema 属性的数据定义。

...
    requestBody:
      description: 自行车信息。
      content:
        application/json:
          schema:
            required:
              - name
              - price
            properties:
              name:
                type: string

完整示例

请求体参数的完整代码如下所示：

post:
  summary: 添加自行车。
  description: 添加自行车到目录中。
  requestBody:
    description: 自行车信息。
    content:
      application/json:
        schema:
          required:
            - name
            - price
          properties:
            name:
              type: string
            price:
              type: number
            weight:
              type: number
            description:
              type: string
  responses:
    "200":
      description: 已添加的自行车信息

小结

一般情况下，在创建或新增一个资源时，用户需要提供资源的信息。这些信息需要放到请求体参数中，发送到服务端。每个资源到操作，都有一个 requestBody 属性，在该属性中，可以定义参数的数据类型和结构。