REST API

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

2022-04-24  本文已影响0人  品品下午茶

可以说，在前面的几篇文章中，我们已经对自行车在线商城的 REST API 进行了详细的设计（通过图和表格）。从今天开始，我们要使用 Open API 规范，对已有的 REST API 设计进行描述，朝着最终的开发实现，再迈进一步。

如果想了解和回顾 Open API 的基础知识，可以参考下面的文章：

如果想了解 Open API 环境的搭建，请参考下面的文章：

本文先对 REST API 的资源和操作进行描述。

创建文档

首先，我们创建一个空白的 Open API 文档，并修改自动产生的标题详细。

openapi: ‘3.0.2’
info:
  title: 自行车在线商城 REST API 文档。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:
  /test:
    get:
      responses:
        ‘200’:
          description: OK

接下来，我们以目录资源为例，对资源和操作进行描述。

把设计转成描述

描述资源

在 REST API 的设计中，我们已经识别出目录资源，并用 /bikes 表示资源的路径。现在通过文档进行描述。

openapi: ‘3.0.2’
info:
  title: 自行车在线商城 REST API 文档。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:  # 1
  /bikes: # 2
    description: 自行车目录 # 3

在 YAML 格式中，可以使用 # 添加注释，这也是 YAML 优于 JSON 的一个地方。

# 1，paths：表示资源的集合，所有资源都要放到这里。
# 2，/bikes：表示目录资源的路径。
# 3，description：对资源的额外描述。不强制，但推荐，很有用。

描述操作

在 Open API 文档中，资源必须包含相应的操作，否则文档是无效的。现在我们来添加查询操作。

openapi: ‘3.0.2’
info:
  title: 自行车在线商城 REST API 文档。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:
  /bikes:
    description: 自行车目录
    get: # 1 
      summary: 查询自行车目录 # 2
      description: |  # 3
        在自行车目录中，使用关键词，
        查询匹配条件的自行车。

# 1，get：get 属性对应的是 HTTP 的 GET 方法。
# 2，summary：表示操作的简短描述。
# 3，description：表示对操作的详细描述。

还记得 | 这个符号吗？在这里可以找到答案。

这时候，文档会提示一个警告：Missing property "responses".。我们必须需要为操作添加一个响应，满足文档的有效性。

openapi: ‘3.0.2’
info:
  title: 自行车在线商城 REST API 文档。
  version: ‘1.0’
servers:
  - url: https://api.server.test/v1
paths:
  /bikes:
    description: 自行车目录
    get: 
      summary: 查询自行车目录
      description: |
        在自行车目录中，使用关键词，
        查询匹配条件的自行车。
      responses:
        “200”:
          description: |
            满足查询条件的自行车

我们添加了一个 responses 属性，表示响应的集合，包含操作所有可能的响应。我们也添加了一个 "200" 响应，表示 HTTP 对状态码，意思是操作成功。最后，description 属性对响应对内容进行了说明。

响应具体包含了哪些数据，我们在后面对文章中进行详细说明。

小结

是不是把设计转换成语言描述很简单？这说明我们对设计工作发挥了作用，让接下来的工作水到渠成。等一等，还缺一个添加操作，请你动手写出来吧。

上一篇下一篇

猜你喜欢

热点阅读