可以说，在前面的几篇文章中，我们已经对自行车在线商城的 REST API 进行了详细的设计（通过图和表格）。从今天开始，我们要使用 Open API 规范，对已有的 REST API 设计进行描述，朝着最终的开发实现，再迈进一步。
如果想了解和回顾 Open API 的基础知识，可以参考下面的文章：
- API 入门 (4) OpenAPI 文档结构
- API 入门 (5) OpenAPI 的 Paths 对象
- API 入门 (6) OpenAPI 响应内容
- API 入门 (7) OpenAPI 参数和载荷
- API 入门 (8) OpenAPI 组件对象
- API 入门 (9) OpenAPI 文档字段和示例
- API 入门 (10) OpenAPI 服务器
如果想了解 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 属性对响应对内容进行了说明。
响应具体包含了哪些数据，我们在后面对文章中进行详细说明。
小结
是不是把设计转换成语言描述很简单？这说明我们对设计工作发挥了作用，让接下来的工作水到渠成。等一等，还缺一个添加操作，请你动手写出来吧。
网友评论