人不会因为使用了什么工具而变得更优秀，只是优秀的人会理智的判断工具的优缺点，然后选择更优秀的工具。
目前文档生成工具有很多，比如使用非常广泛的swagger，基于它的名声和朋友的推荐，我使用过一段时间的swagger。
swagger的优缺点很明显:
优点：它有一套完整的注解，可以非常详细的描述每一个api接口的各个信息，并且提供了一套网页，能直接在网页上测试接口。
缺点：缺点也是它的注解，过于庞大的注解体系；
- 学习成本，程序员需要去理解并记住它自己的一套注解体系；
- 注解与注释的矛盾，方法头上加注释描述这个方法的作用与使用方式本就是一种良好的编程习惯，但是如果加了swagger注解又写一次方法的描述，有很多时候就感觉重复没必要，导致很多人在接口方法上就不写注释，用swagger注解来表示注释，这本就是对编程习惯的入侵，养成不好的编程习惯；
- 是swagger的注解让方法看起来奇丑无比，有时候比普通代码还多，整个controller就像是被swagger的注解充斥着一样，代码一点都不优雅。
所以我并不是很喜欢使用swagger作为我的文档生成工具，我认为文档写一遍就好了，作为java程序员，做什么文档的事情，写好注释就好了，注释本身就是文档，只需要一个工具，从代码中把注释提取出来形成专门的文档就好了。
我开始找到的是JAPIDOCS，它通过maven引入jar包到项目，做一些简单的配置就能使用，它会生成html文档到项目目录下，无需写注解，直接根据方法上的注释生成文档，非常ok，我使用过一段时间，后面停止使用是因为文档每回更新都需要重新生成然后通过其余社交软件发给前端的同事，非常不方便，而且当时生成上还是有一些问题，具体不记得了，不知道现在修复没有。
再后来发现了EasyYapi，非常符合我的需求，并且是我一直使用到今天的文档生成工具，目前已经使用一年多了，下面我来介绍一下它的优点：
1.完全无侵入式
本人使用IDEA进行开发，无需引入任何jar包，也不需要编写任何配置，只需要在插件市场搜索EasyYapi，安装这个插件重启即可，如下图所示：
image.png
2.文档生成种类丰富
它可以直接将文档导出到yapi、postman、makerdown和pc文档，如果是团队合作，可以结合yapi使用，非常方便，我目前就是使用这种方式，写好代码后直接用快捷键生成并推送文档到yapi上（怎么搭建yapi平台自己百度），前端直接在yapi上查看接口文档。
image.png
3.贴合编程习惯的注释方式
它完全符合我们常规的注释习惯，无需学习什么专门的注释，更方便生成文档的同时，还可以养成良好的编程习惯。
image.png
这里只是做介绍，具体使用方式可以直接看官网文档
文档地址：https://easyyapi.com/documents/index.html
最后，现在我们公司都是使用的EsayYapi结合yapi食用，本人也算是使用经验比较丰富吧，使用过程中有什么问题可以留言讨论。
网友评论