问题：手写API文档的几个痛点？
1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2. 接口返回结果不明确。
3. 不能直接在线测试接口，通常需要使用工具，比如postman。
4. 接口文档太多，不好管理。
Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。
一、Swagger简介
1.1、Swagger概述
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。
1.2、Swagger作用
1.2.1、接口文档的在线生成。
1.2.2、功能测试。
1.3、Swagger工具
1.3.1、Swagger Editor
可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的Swagger
JSON描述，并用于所有Swagger工具（代码生成、文档等等）中。
1.3.2、Swagger UI
一个无依赖的HTML、JS和CSS集合，用于解析遵守Swagger spec的JSON或YAML文件，并且生成API文档的UI导航。
1.3.3、Swagger Codegen
可为不同的平台生成客户端 SDK（比如 Java、JavaScript、Python等）
1.4、Swagger示例
二、Swagger集成
2.1、引入springfox依赖
2.2、创建Swagger配置类
2.3、引入swagger UI
2.4、controller注解
常用注解说明:
@ApiModel：用于类，描述一个model的信息
@ApiModelProperty：用于方法，字段，表示对model属性的说明
@Api：用于类，表示标识这个类是swagger的资源，并说明该类的作用
@ApiOperation：用于方法，给API增加方法说明，说明方法的具体作用
@ApiParam：用在请求方法的参数上，表示对参数的说明
@ApiImplicitParam: 用在方法上表示单独的请求参数
@ApiResponses：用在请求的方法上,表示一组响用
2.5、结果展示
输入参数，点击“Try it out”
注意：
1.springfox的注解配置含@EnableSwagger2 和 @EnableSwagger。
@EnableSwagger2: 指的是采用Swagger API Spec 2.0,此时springfox获取json路径为http://IP:port/{context-path}/v2/api-docs。
@EnableSwagger: 指的是采用Swagger API Spec 1.0,此时springfox获取json路径为http://IP:port/{context-path}/api-docs。
2. springfox的入口是一个controller，需要用Spring MVC进行拦截。
三、Swagger与公司项目整合
3.1、引入依赖
开发好swagger微服务模块项目后，直接添加swagger项目依赖即可集成swagger项目到公司项目，本例集成到bee_admin。
3.2、结果展示
先后启动好注册中心，配置中心，admin三个微服务模块，输入URL
http://192.168.0.109:11082/swagger2-demo/swagger-ui.html#/
随机测试一个menucontroller.
3.3、响应页面具体说明
四、生成静态HTML5，PDF的API文档
在配置好插件后，只需点击并执行“asciidoctor”命令，便可生成对应的HTML5，PDF文档。
五、Swagger 总结
优点：
1.编写代码的过程中，可以实时的产出接口文档，对于文档的维护非常方便。
2.文档结构清晰，界面美观，便于项目内部交流。
3.方便测试人员和前端开发人员了解API。
4.支持通过API规范生成客户端和服务器代码骨架代码，加速开发。
缺点：
1.对代码的嵌入性比较强。
2.无法更换主题。
六、参考地址
swagger官网：http://swagger.io/
swagger规范：http://swagger.io/specification/
swagger editor在线编辑：http://editor.swagger.io/#/
swagger github：https://github.com/swagger-api
swagger 注解说明：
https://github.com/swagger-api/swagger-core/wiki/Annotations#apioperation
springfox github：https://github.com/springfox/springfox
swagger：Rest API的描述语言：https://zhuanlan.zhihu.com/p/21353795
springfox-swagger原理解析与使用过程中遇到的坑：
http://blog.csdn.net/w4hechuan2009/article/details/68892718
API文档工具-swagger的集成：http://www.jianshu.com/p/5cfbe62a1569
swagger：http://www.jianshu.com/p/4115f2b53983