小故事
故事情节:后端又更新了API接口文档,发在交流群里。
在日常工作中,API版本每次更新的时候,需要再次发送一份给前端,容易造成文档交流不及时。尤其是现在提倡前后端分离,更容易造成文档和代码的不一致。本篇文章就来分享一种API文档维护的方式,即通过Swagger来自动生成Restful API文档。
Swagger简介
Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
Swagger优缺点
优点
- 节省了大量手写接口文档的时间
- 通过注解自动生成在线文档
- 接口在线调用调试
缺点
- 代码耦合,需要注解支持
- 代码侵入性比较强
- 无法测试错误的请求方式、参数及不限于这些
手动API痛点
- 文档更新的时候,需