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

我们在使用 OpenAPI 规范描述资源和操作时，只是对操作的响应进行了简单的描述。从本文开始，我们将要对操作的输入和输出的数据进行详细的描述。

首先，我们要对输入数据，也就是操作的参数进行描述。为了查询一辆自行车，我们要发送这样一个请求：GET /bikes?key={value}. 为了描述这个参数，我们需要为 /bikes 资源的 get 操作增加一个 parameters 属性，并添加查询参数 key：

openapi: '3.0.2'
info:
  title: 自行车在线商城 REST API 文档。
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /bikes:
    description: 自行车目录
    get: 
      summary: 查询自行车目录
      description: |
        在自行车目录中，使用关键词，
        查询匹配条件的自行车。
      parameters: #1
        - name: key #2
          description: | #3
            自行车的名称，编号或描述的部分信息
          in: query #4
          required: false #5
          schema: #6
            type: string
      responses:
        "200":
          description: |
            满足查询条件的自行车

parameters 属性是一个数组，数组中每个元素都表示一个参数，并以短横线（-）开头。一个参数必须包含name、in和schema三个属性，required 和 description 是可选属性。

下面对 6 个注释对地方进行重点解释：

• #1，参数的名称
• #2，参数的描述
• #3，参数的位置，query 表示查询参数
• #4，表示参数是否必须提供，默认值 false
• #5，参数的数据结构
• #6，参数的类型

在 schema 属性中的数据结构，其实是一个 JSON 的 schema. Open API 文档就是使用 JSON 的 schema 描述数据结构。schema 不只是包含一个 type 属性，还可以描述更复杂的数据结构。在描述请求体参数和响应数据时，我们就会用到。

小结

在本节中，我们为查询自行车的操作添加了查询参数，并使用 schema 属性定义了查询参数的数据结构。