（3）本来swagger的API定义应该由架构师或项目经理编写，但由于后端开发人员可以直接改文档，这导致的实际效果就是：基本上API文档都直接由开发人员编写（或修改），其质量水平很难达到期望；
（4）swagger生成API文档的类的定义可能是多层引用关联的，但是这个类又太容易被开发人员修改到，或者不小心改到，如果开发人员忘记通知前端或者只通知了部分改动，那就会造成严重的问题；
（5）使用swagger的语法来编写API文档，其实还是很麻烦的，我们希望这个语法能够超级简单；
（6）swagger会污染你的代码。
关于上方的第（1）点，笔者想跟大家分享一些工作中的趣事。以前我们团队使用swagger的时候，有时我们的java开发人员发现某个字段的命名写错了，但是他以为客户端开发人员还没有做这个功能，就悄悄的将命名修正了。后来测试提交了BUG。。。。
本文列出的swagger的这些缺点，其实每一个都不算大，这也是这么多团队可以一直忍受它的缘故。swagger的这些缺点其实综合来讲，其主要的问题就在于它让API编写/修改太过容易，让软件开发过程和管理过程太容易出错。如果你们团队建立了严格的管理机制，那还是可以将swagger用的很和谐的，但这不是笔者，作为一个架构师，可以撇开责任的理由。
作为一个架构师，笔者以为一个好的框架应该让开发人员不那么容易犯错，甚至杜绝了开发人员写出错误的代码。关于这一观点，笔者会在另外的文章中以我们对hibernate的改造为例，进行更详细的阐述：如何让开发人员更不容易写出错误的代码是评价一个架构师能力的重要标准。
行文至此，笔者已经残忍的批判了很多团队的API文档方案，如果让您感觉不适，我只能深表歉意了。
在说其他方案的缺点时，其实笔者已经逐渐透露了我们自创的API文档服务框架将要解决的问题了。那么，接下来请看我们的解决方案，以及我们为什么这么设计。
第三章 我们自创的API文档服务框架详解 1、我心目中的API文档服务器应该是什么样子？
笔者在写代码或做架构的时候有一个思维习惯，就是不管某个问题多么复杂具体解决方案是什么，我会先去想想这个问题的最佳的处理方式应该是什么样子，然后再去想这些最佳的处理方式哪些可以实现，哪些实现不了而只能用次一点的方案，然后次一点的方案是否可以接受。
对于API文档服务框架，在我的心中早已有了期望：
（1）编写API文档的语法一定要非常简单，同时又要非常灵活，对于大多数常见API必须能够快速编写，对于某些特殊API，又能够支持自定义编写；
（2）每一个API文档能够非常容易的定义请求和响应数据结构，最好能够自动生成请求和响应示例，更重要的是，生成的示例必须看起来是符合业务需求的真实数据；
（3）能够非常方便的编写JSON格式的数据；
（4）API文档的发布要非常简单，最好能在几秒钟内完成；
（5）API文档的源文件最好独立于项目源码，不能污染项目源码；
（6）每次修改API文档，最好能够自动创建版本历史记录，同时要能够非常方便的查看历史版本；
（7）能够通过WEB浏览器访问；
（8）API数量达到成千上万的时候，能够呈现一个树形目录结构，方便阅读和搜索；
好了，大概就这8个特性吧，下面请看我们是如何完成的。
2、我们自创的API文档服务框架核心工作原理首先请看简易框架示意图：
这个框架搭建起来并不复杂，甚至可以说是很简单的。所用到的技术和工具如下：
（1）使用JavaScript作为API文档源文件的编写语言；
（2）使用任何支持JavaScript的IDE作为API文档编写工具，我们团队使用intellij idea；
（3）使用SVN服务器作为版本管理工具，用来管理API版本；
（4）WEB服务器可以随便使用哪个框架搭建。
核心工作原理（4步）：
1、获取JS目录结构。当用户在浏览器中输入API文档服务地址（如：）时，WEB服务器根据事先配置好的SVN地址和账户信息，从SVN服务器获取JS文件（即API定义源文件）目录，然后WEB服务器将这些JS文件的树形目录响应到浏览器（非JS文件内容，仅仅是JS目录结构），后面当用户点击某个JS文件名称时，才会加载相应JS文件内容，这样即使当API文档增加至上万个，也不会太大影响加载速度。