后端老是不写接口文档？说自己很忙？

Posted 2021-12-14 隔壁王书

自从前端和后端分家之后，前后端通过接口对接就成为了日常，谁也离不开谁，而对接接口的过程就离不开接口文档。

理想的前后端均衡的团队里，流程一般是这样：
1、大家一块讨论需求，分析实现细节；
2、由前端或后端中的一方提出来一版初版接口文档大家来讨论；
3、最后讨论定了后大家各自进行程序开发实现，当然这个过程中会有一些字段细节的增删调整，不过一把大结构上是不会有太大变化了。

这种理想情况下，哪一边出接口文档，他们都是比较乐意的，因为这就相当于标准制定啊，谁来出谁就可以按自己方便的来。

不过嘛，实际情况往往都没那么理想，每个公司多多少少都会有前端偏向性或是后端偏向性，后端偏向性的结果之一，就是迟迟不给接口文档，美名其曰开发任务多，没空写文档了。

有需求了肯定就有解决方法，如果是开发 http api ，那么一般都会用像Swagger、Eolink等接口文档管理工具来辅助接口文档的相关工作，这两个工具也都支持先写代码或先写文档的两种方式。
1、先写代码，通过注解生成文档。/2、先写文档，再借助工具生成代码脚手架，然后填充业务逻辑部分。

在国内，先写代码再自动生成文档的方式特别常见，笔者通常都是用的Eolink，功能和Swagger差不多，但是因为是国内团队设计的，服务支持比较方便。编辑好API模板，就可以直接生成规范的接口文档，API有修改也可以一键同步到接口文档。

而先写文档再写代码的所谓 design first 方式极其罕见，笔者在工作中至今没见过一例，也只在个人项目中实践过这种方式，不算熟悉，就不多讲了。

Swagger：https://editor.swagger.io/
Eolink：https://www.eolink.com/product/api_studio/