背景
前后端分离的工作模式下面,API交互文档亦然成为前后端沟通最佳介质。依赖文档,简化沟通,提高写作效率。
文档如何形成
API文档应有前后端共同约定,商议。实际开发中API文档由后端同学维护,因为前端是API的消费者。提供文档的方式有很多种:
Txt,Markdown , Word
原始,文档作者手动录入,接口变动需要以来文档作者实时更新,易读性取决于作者.
文档没有集中管理方式文档平台(公司内部文档平台)
文档集中管理,手动录入,同步不够简化,文档结构有同意约束Swagger 文档
文档自动生成,前期会增加额外的后端同学开发工作 ,文档详细。接口变动实时同步
前端如何消费API文档
API文档规定了API URL
,API RESPONSE
,API RESQUEST
,前端同学按照文档格式编写交互代码,有几种方式
- 手写模拟JSON ,直接请求
- 手写模拟JSON ,使用 NGINX 或者 NODE 转发
- 使用构建工具(FIS3,Webpack)内置的Node服务转发JSON,或者是本地启动Node sever
- MOCK SERVER 平台
- 本地直接代理到后端服务(这种场景仅限于后端工作前置前端许多)
总体来说,前端消费API文档不外乎几点
- 手写JSON && 自动生产JSON
- 本地转发 && 统一平台管理
AMP
Api Manage Platform 是2016-10-10
部署在公司内网的一个简易MOCK SERVER 服务。提供的功能有:
- 注册,登陆,项目权限控制
- 手动录入API,生成MOCK地址
- 录入Swagger json , 自动生成API文档与MOCK 服务
- 简单的接口检测工具
Easy-Mock
Easy mock 是2017-09-10
部署在公司内网的一个简易MOCK SERVER 服务。提供的功能有:
- 注册,登陆,项目权限控制
- 手动录入API,生成MOCK地址
- 录入Swagger json , 自动生成API文档与MOCK 服务
- 项目复制与接口复制
- 可视化接口数据编辑
- 打包下载全部接口
- mockjs-支持生成随机的文本、数字、布尔值、日期、邮箱、链接、图片、颜色等
- mockjs-支持扩展更多数据类型,支持自定义函数和正则
- 支持响应式数据(自定义JS函数)
- 支持数据代理(这个功能暂时是鸡肋)
- 支持JSONP
- 支持restful接口
- 结合(easy mock cli)生成请求函数,在我们react体系中应用不大,可以改造
EASY-MOCK | 亮点 | 需要优化与BUG |
---|---|---|
支持Swagger,自动与手动编辑接口 | swagger仅支持标准openapi范式,公司内部swagger多数有自定义格式,swagger支持不是很好 | |
支持Mockjs与响应式数据 | 接口代理功能属于鸡肋 | |
可视化数据编辑 | 快捷键容易造成误操作(已经提issues) | |
接口复制,项目克隆 | 官方维护貌似挺慢的 | |
项目接口打包下载 | 暂未支持版本管理与DIFF |
Easy-mock 解决了什么
项目统一的文档管理与接口服务
前端MOCK服务,后端录入文档,前端可以直接使用,不用本地增加任何开发设施(转发服务,本地JSON生成)
原有流程:API文档(找个位置放着) => 前端手动翻译成MOCK JSON => 设置本地代理或者转发 => 交互开发
改后流程:EASY MOCK API文档 => 交互开发
丰富了前端MOCK方式与更多功能性
总结与建议
前后端开发文档应当集中管理,而不是根据项目走
前后端API文档应该由前后端共同约定
尽量统一公司内部文档格式,如果不是swagger的话,可以共同约定一种格式
如果项目的文档提供方式是以手动书写(MD , TXT , DOC)提供的话建议直接迁移到
接口平台(Easy-mock),方便管理与记录
其他(开源mock平台)
AMP@小爝团队开源产品与Easy-MockBy芋头团队开源产品