我们在使用 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
属性定义了查询参数的数据结构。
网友评论