软件开发中的接口文档这个东西，目前还真没有十全十美的解决方案，很容易引发前后端撕逼大战。
用swagger文档的公司不在少数，但swagger是个很糟糕的东西：
1、首先，swagger对代码的侵入性太强，为了一份接口文档，项目里所有的接口方法、DTO、VO等都需要加swagger注解；2、其次，许多后端程序员以用的swagger文档为借口，开发完再给接口文档，这就导致了一系列前后端撕逼大战；
3、然后，swagger还需要在开发环境和生产环境做配置，接口文档不能直接在生产环境暴露。
以rap2、yapi等为代表的另一种接口文档也不完美：
1、即使能用json导入接口参数，也觉得很麻烦。2、随着产品迭代等原因，对以前接口做了修改，那么很多懒惰的程序员根本不会去改对应的文档，导致后人拿到错误的接口文档。
另外，后端都喜欢接口开发完之后再给文档，前端都希望开发前就定好接口文档。理论上来讲，应该先给出文档，但这两种做法其实各有优缺点：
1、后端开发完再给文档，一是延误进度，二是前端可能不认可你返回的数据格式，要求改，从而引发前后端撕逼大战。
2、如果事前给出接口文档，那就别指望后面不会改，菜鸟程序员占多数，代码写一半发现这样设计不好，所以要去改接口参数，甚至有些后端是偷偷改的，改完不告诉前端，往往又会引发前后端撕逼大战。
高谈阔论