在上面这个流程中，API文档环节直接关系到了前端和后端两个开发团队，也是整个软件开发流程中耗时最大的环节。一旦API文档编写不合理，或者维护太麻烦，或者阅读不方便，将极大的影响开发效率，影响团队士气。而其他环节通常不会跨部门耦合，常用解决方案非常成熟，并且所消耗的资源也远不及开发团队，因此，API文档环节就变成了前后端分离团队中最关键的环节。
如果你曾经参与过前后端分离团队的开发工作，那你很可能对上文描述的场景深有体会。
接下来笔者说说为什么API文档服务器是最困难的环节。这也是为了让大家做足心理准备：搭建API文档服务器并没有想象那么容易。
首先，最大的难点在于这个世界上已经有大量现成的API文档服务方案，比如用Word/Excel来做API的载体，或者使用类似swagger这样的框架。我们大多数架构师，包括笔者在内，的第一反应就是找现成的，然后去对比各个现成的方案，对比每个方案的实施难度以及适用度。我们（指架构师们）最终找来找去，其实也没有找到一个完美的方案，但不得不从各个现成的方案中选择一个，我们很少去想有没有可能自己来搭建一个，即使有时候想着自己去搭建一个，但是往往一想到其中的困难（甚至无从下手）以及项目进度压力，可能就浅尝辄止了。
笔者的团队在2018年以前的项目中也使用过word文档和swagger，但我是一个追求完美的人，我一直没有停止思考去搭建一个完美的API文档服务器方案，直到2018年3月，终于灵光一现，解决了搭建过程中的一个关键问题（API版本管理），于是才有了我们团队的前后端分离之路。
其实，本文所阐述的方案对于使用者来讲也可以说是现成的了，因为每个人注册个账号就可以使用。但是本文的目的并不只是简单的告诉大家我们做了一个新的API文档服务器，而是想跟大家分享我们为什么要做这个文档服务器，以及为什么这样做。
3、为什么我们不用word文档作为API文档的载体？
用word文档（或者Excel）算是最落后的方式了吧，其缺点很明显：
（1）API一多，维护和阅读就变得极其困难；
（2）每次API文档修改之后，需要修改者自己去维护版本修改记录，这操作是违背人性的，并且如果想要基于单个API维护版本历史，那可以算得上违背天理了；
（3）在word里面写JSON格式的数据结构是很难的，如果用截图那就极大的增加了维护成本；
说完word文档的缺点，按照套路应该说说word文档的优点了吧。好吧，word文档的优点就是方便传播、离线阅读，但是除非你们项目的API文档的维护频率是按年计的，那还是早早放弃word吧。
4、为什么我们不用swagger（及类似方案）？
考虑到本文的读者有可能从未接触过swagger，笔者首先得说说swagger是做什么的，以及它的先进性（没有一定的先进性怎么会得到这么多人的追捧是吧）。
swagger是一个API文档生成框架，说白了它是一个类库，集成到系统之后，能够通过反射读取后端代码定义的API文档，java和.NET体系下都有对应的版本。
swagger最大的先进性：不需要专门有人来编写API文档，自动根据代码生成API文档，API文档维护成本极低。swagger还有其他一些小优点本文就不细说了，因为那些都不是大家选择swagger的主要原因。
那swagger到底有什么不够完美的地方让我们团队最终完全放弃了swagger？
swagger之不够完美的地方：
（1）通过swagger生成的API文档看不见版本修改记录，你不知道什么时候后端开发人员悄悄改了下API文档而忘记/有意不通知前端开发人员，这样的锅前端背了太多；
（2）接口文档由后端开发人员编写，前端开发人员的地位实际上比后端的低，并且前端开发人员仍然会经常找后端开发人员沟通修改API文档（强依赖仍然存在）；