swagger 不是开发完再给接口的借口。后端开发完,前端再对接接口这个时间会远比先花时间定义好接口要多很多,前期前端在等接口,后期后端在等前端调试…
实际开发中个人不建议非要学主流的api文档方案,比如swagger,代码侵入性还是比较大的,个人不太喜欢。
选择一个最适合团队,切入成本最低的协议文档方案,前后端都可以方便的去接入,哪怕只是个单纯的文字文档,规定好常用的协议格式也不失一个好的解决方案。
核心在于前后端要提前做好对api接口的约定,先于业务代码开发之前。这样前后端一旦形成约定就可以各自开发了,当然,实际开发中协议难免会变,减少变化的方案可以做一轮review,及时更改接口协议。开发中不建议轻易做协议变更,变更前要思考清楚为什么变化?是业务没想清楚还是需求变更了?
当然,也有很多工具可用,在实际团队中我有试过easyapi,小幺鸡,但easyapi功能比较单一,小幺鸡之前版本生成的文档够丑,后来选择了yapi,私有化部署了一份,支持接口定义和mock,前端可以自己根据接口做mock测试,不用等后端接口,后端也可以把yapi用做接口测试工具,总体互相之间的依赖减少了。
简单粗暴但有效可以直接使用共享文档写api协议,协议一目了然:
也可以使用更强大的带mock测试的api工具,在定义协议时可以直接就把mock接口写上,前端开发中不要太high:
工具不是解决问题的根源,根源在于团队要共同遵守一个合理的开发流程,不要只顾着自己闷头撸代码,对于团队leader来说在定义功能完成度上可以把前后端全部联调完定义为功能真正完成,否则只开发完接口不算任务的结束,以整个功能的完成作为deadline指标。