美文网首页REST APIjs css html
API 入门 (28) 使用 OpenAPI 描述 REST A

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

作者: 品品下午茶 | 来源:发表于2022-04-25 08:54 被阅读0次

我们在使用 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 属性是一个数组,数组中每个元素都表示一个参数,并以短横线(-)开头。一个参数必须包含nameinschema三个属性,requireddescription 是可选属性。

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

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

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

小结

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

相关文章

网友评论

    本文标题:API 入门 (28) 使用 OpenAPI 描述 REST A

    本文链接:https://www.haomeiwen.com/subject/lxutyrtx.html