Swagger2 与 springmvc 集成实现API文档化

为什么要实现API文档化？

1. API文档化有利于前后端分离的开展。随着开发方式全面转成前后端分离，前端和后端的唯一沟通就在API层面。在没有文档化之前，开发人员只能口头的交代并反复理解每个接口参数和返回值，这个过程相当不稳定，变化频繁。而通过API文档化后，可以通过文档的清晰定义，使得前后端人员减少无畏沟通，并在理解上保持一致；

2. API文档化有利于接口自动化测试。公司马上上马接口自动化测试，对接口参数和返回值要通过Json方式导入自动化测试程序。而用特殊工具生成的API文档，可以直接输出json格式的文档，简化了测试流程，减轻了开发人员的工作量；

3. API文档化有利于系统文档建设。开发人员不愿意写文档，写注释。而为了以上两个目的必须要求开发人员在编码的同时补充相关的API描述，而通过一个相对稳定成熟和趁手的工具可以大大减轻文档的工作量，做到事半功倍。

Swagger和spring-boot-starter-swagger

Swagger是业界比较流行的实现API文档化的工具。优点有

1. 通过在项目中引入Swagger，可以使用简单的Annotation，就实现了API文档化；
2. Swagger提供标准的json或yaml文档，方便做进一步解析，典型应用是接口自动化测试；
3. 页面可以直接进行测试（try-it-out功能，部分替代Postman）；
4. Swagger还提供类似于github的SwaggerHub，相当于公共的API文档集散地。

Swagger的项目主页：https://swagger.io/

搭建和使用 可以参考以下网址：

微服务之Swagger ：https://www.cnblogs.com/softidea/p/6251249.html 

SpringBoot学习笔记之集成swagger ： http://blog.csdn.net/liyuejin/article/details/78036582

springfox github : https://github.com/springfox/springfox

springfox &Swagger2的API

http://springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot