背景
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
没有API文档工具之前，大家都是手写API文档的，在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏（其实相比于Swagger，都不好）。
书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。
swagger的生态使用图
Springfox解释
swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。
由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox-swagger2。
pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。
Swagger是一款 RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的Web服务，加上 swagger-ui，可以有很好的呈现。
与SpringBoot集成的步骤
第一步：导入依赖（本文采用SpringBoot2+springfox2.9.2版本）
<-- boot相关依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--整合swagger--> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
第二步：书写SwaggerConfig配置文件
/** * @author fangshixiang * @description * @date 2018-11-14 10:48 */ @EnableSwagger2 //开启springfox的Swagger2 @Configuration //@Profile("dev") //只有在测试环境才开启Swagger public class SwaggerConfig { //是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置 //若配置类上写了使用了@Profile 也可以达到类似效果 二选一 此处默认值为true @Value(value = "${swagger.enable:true}") private Boolean swaggerEnable; /** * 创建一个Docket 并且注册到Spring容器里即可完成配置 * * @return Docket */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) //是否开启 .enable(swaggerEnable) //设置API描述信息 .apiInfo(apiInfo()) .select() //扫描的的包 一般定位到controller那即可（若有接口层，此处报名需要注意） .apis(RequestHandlerSelectors.basePackage("com.fsx.run2.controller")) // 指定路径处理：PathSelectors.any()代表所有的路径 // 也可以指定某些接口不要对外暴露 这里定义一些规则就行 如正则表达式 .paths(PathSelectors.any()) .build() //base，最终调用接口后会和paths拼接在一起 .pathMapping("/"); } //设置API信息 一些简单的描述信息而已 private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API Document for 自定义服务名") .description("API描述信息") .contact(new Contact("Fangshixiang", "https://www.baidu.com", "shixiangfang@aliyun.com")) .version("1.0.0") .build(); } }
第三步：书写测试的Controller类
@RestController @RequestMapping("/demo") @Api(tags = "Demo API接口文档") public class DemoController { @ApiOperation("根据id获取一条记录") @GetMapping("/{id}") Object getById(@PathVariable Integer id) { return id; } }
最后，启动项目，访问：http://localhost:8080/swagger-ui.html
这样，API文档就自动生成了，我们只需要把这个连接发给前端，前端就能对API接口的相关数据结构一目了然，体验非常好
强烈建议在生产环境关闭 swagger,避免不必要的漏洞暴露！
Springfox简单原理
在前言中，我们知道，我们的第一个任务就是生成一个满足OSA规范的json文件（当然，创建一个spring的项目就不说了）。对于这个任务，springfox为我们提供了一个Docket（摘要的意思）类，我们需要把它做成一个Bean注入到spring中，显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。
这就是Springfox的强大之处，他启动时候回去扫描包下的controller，然后组装成json，然后放在内存里。最后提供UI界面直接访问即可，非常方便。
Swagger其余小组件介绍
swagger-editor（需要单独安装在操作系统上，使用较少）
就是一个在线编辑文档说明文件（swagger.json或swagger.yaml文件）的工具，以方便生态中的其他小工具（swagger-ui）等使用。
左边编辑，右边立马就显示出编辑内容来。
swagger-codegen
代码生成器，脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。 有一定用处，Java系用的挺多。
对于从来不喜欢自动生成代码的我，觉得鸡肋
swagger-validator
这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。
最后
Swagger在分布式环境下，可以结合网关聚合API文档，具体参考：
利用swagger2聚合API文档
聚合API文档在开放过程中，可以大大提高效率，值得推荐
