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

当我们在检索、更新或删除自行车资源时，需要通过路径指定要操作的资源，如下所示：

GET /bikes/{bikeId}
PUT /bikes/{bikeId}
DELETE /bikes/{bikeId}

可以看到，路径中包含了一个路径参数{bikeId}，使得 /bikes/{bikeId} 成为一个可变路径。换句话说，bikeId(自行车标识)取不同的值，路径指向的资源就不同。但是，只要bikeId的值一定，在执行检索、更新或删除操作时，返回的自行车信息就是同一个资源的。

下面，我们使用 OpenAPI 规范，对检索和删除操作进行描述，看看能否发现一些问题。

检索自行车

下面是检索自行车的示例代码。

  /bikes/{bikeId}:
    description: 自行车信息。
    get:
      summary: 检索自行车。
      parameters:
        - name: bikeId
          in: path
          required: true
          description: 自行车标识
          schema:
            type: string
      responses:
        "200":
          description: 对应标识的自行车信息

删除自行车

下面是删除自行车的示例代码。

  /bikes/{bikeId}:
    description: 自行车信息。
    delete:
      summary: 删除自行车。
      description: 删除一个指定的自行车。
      parameters:
        - name: bikeId
          in: path
          required: true
          description: 自行车标识
          schema:
            type: string
      responses:
        "200":
          description: 已删除的自行车信息

发现问题

通过比较上面两个操作的描述信息，我们可以很容易发现，路径参数的描述信息是相同的。

  parameters:
    - name: bikeId
      in: path
      required: true
      description: 自行车标识
      schema:
        type: string

不要重复发明轮子，那该如何处理呢？使用组件。

参数组件

在组件集合属性中，不仅可以定义可重用的 schema，也可以定义可重用的参数。

components:
  parameters:
    bikeId:
      name: bikeId
      in: path
      required: true
      description: 自行车标识
      schema:
        type: string

引用参数

接下来，在检索自行车和删除自行车时，我们就可以引用 bikeId 路径参数了。

paths:
  /bikes:
  [...]
  /bikes/{bikeId}:
    get:
      parameters:
        - $ref: #/components/parameters/bikeId
      [...]
    delete:
      parameters:
        - $ref: #/components/parameters/bikeId
      [...]

还有问题

你一定又发现重复的数据描述了。下面的描述信息出现了两次。

- $ref: #/components/parameters/bikeId

如果考虑到更新自行车时，也会使用相同的描述，这一行信息会出现 3 次。能否消除这种重复的情况呢？

资源参数

路径参数 bikeId 被定义了一次，在检索和删除两个操作中进行了引用。需要明确的是，路径参数 bikeId 不是操作层级的参数，而是资源层级的参数。因此，我们可以在资源属性下面进行定义，这样，就可以省去在每个操作中进行定义。

components:
    parameters:
      bikeId:
        [...]
paths:
  /bikes/{bikeId}:
    parameters:
      - $ref: #/components/parameters/bikeId
    get:
      [...]
    delete:
      [...]
    put:
      [...]

这样看起来，是不是更加完美了。

小结

我们使用组件对象，定义了路径参数，避免在多个资源操作中进行描述；然后，我们路径参数的引用，放到了资源层级的参数中，不必在每个操作中重复引用。经过两次重构，文档变得更加简洁，清晰。