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

我们在对资源和操作进行描述时，添加了 responses 属性，并且只是添加了 HTTP 状态码和描述，满足文档的有效性，并没有说明应该包含什么数据。本文继续对响应数据的内容进行详细的定义。

当用户查询自行车时，如果查询操作执行成功了，服务端响应的 HTTP 状态码为 200 OK，服务返回的响应数据应该包含满足条件的所有自行车，是一个资源的集合。

在 OpenAPI 中，使用 JSON Schema 对响应数据的结构和内容进行定义和描述。下面是查询自行车操作成功执行后，响应数据的示例代码：

  responses:
    "200":
      description: 满足查询条件的自行车
      content: #1
        application/json: #2
          schema: #3
            type: array #4
            description: 自行车集合
            items: #5
              type: object #6
              description: 自行车实体对象
              required: #7
                - reference
                - name
                - price
              properties: #8
                reference: 
                  description: 自行车唯一标识
                  type: string
                name:
                  type: string
                price:
                  description: 自行车单价
                  type: number

具体说明如下：

• #1，HTTP 响应的数据都包含在 content 属性中。
• #2，application/json 属性表示响应的数据类型，此处是 JSON 格式。
• #3，schema 属性定义了响应数据的结构，也就是 JSON 的数据结构。
• #4，表示响应的数据类型是一个数组。
• #5，items 属性表示数组的集合。
• #6，type 属性表示数组里元素的类型。
• #7，required 属性表示哪些自行车的属性是必须存在的。
• #8，properties 属性表示返回的自行车属性列表。

下面是一段响应数据的示例：

[
  {
    "reference": "B007",
    "name": "的卢",
    "price": 999.99
  },
  {
    "reference": "B008",
    "name": "赤兔",
    "price": 1999.99"
    }
  }
]

小结

在 OpenAPI 文档中，使用响应的 content 属性，包含返回的实际数据。我们使用 JSON Schema 描述了自行车信息的数据结构，并把他们放到了响应数据的数组中。接下来，我们将学习如何描述请求体的参数。