关于Restful API文档和接口测试

前后端分离

提高前后端的开发效率是非常必要的,那么如何利用好RESTful标准来做好前后端分离呢?

规定API标准

RESTful API

当然你也可以制定自己的API的标准,使用开发人员的编程习惯来决定会比较人性化。这里我选择用 RESTful API 来举例。

REST全称是 Resource Representational State Transfer 翻译为表现层状态转移

用一句话表示其含义为 用URL定位资源,用HTTP动词(GET,POST,DELETE,PUT,PATCH)描述操作

API 全称是 Application Programming Interface 翻译为应用程序编程接口

关于 RESTful api 的设计可以参考阮大的博客 RESTful API 设计指南

API 编写工具

Swagger 是一套开源的API管理工具

其中 Swagger edit 是Swagger推荐的工具,你可以选择在线编辑,或者在本地部署一套自己的github Swagger edit

然而我推荐使用 vscode 编辑器的两个插件 OpenAPI (Swagger) EditorSwagger Viewer 来编写。

这两个编写工具相比较,vscode有更舒适的字体,字号和配色,但是debug能力稍弱于swagger-editor,所以debug难时也可以配合使用。

目前swagger常用的版本有 swagger: ‘2.0’ 与 openapi: 3.0.1,两个版本中openapi更为强大,但我最后还是选择了swagger: ‘2.0’, 原因在最后面。

API 查看工具

本地部署一套 Swagger UI 吧,还是比较好用的,记得每当更新接口后,查看浏览器要强制刷新。

接口测试工具

要做到前后端松耦合,并行开发,利用接口测试工具是至关重要的。

Postman 后端的接口测试工具

mock 前端的测试工具,这里我推荐 easy-mock 国人主导的开源项目,表示支持,也确实很好用。

关于easy-mock

这个工具也推荐本地部署,它支持swagger yaml和json格式的api 文档加载,自动生成后端接口和模拟返回数据,真正解决前后端并行开发难的问题。

之前说,我选择swagger: ‘2.0’是因为加载openapi3.0后 easy-mock 生成模拟数据失败了,可能是兼容性还没做好,或者是我的文档语法上有坑没排查出来,这个项目现在已经6k+的star了,之后应该可以完美兼容openapi3.0