SpringBoot整合Springfox-Swagger2「建议收藏」
SpringBoot整合Springfox-Swagger2「建议收藏」
大家好，我是架构君，一个会写代码吟诗的架构师。今天说一说SpringBoot整合Springfox-Swagger2,希望能够帮助大家进步!!!
前言
不管Spring Boot整合还是SpringMVC整合Swagger都基本类似，重点就在于配置Swagger，它的精髓所在就在于配置。
@
目录 1、Swagger简介
目前互联网时代前后端分离已成趋势，前后端混在一起，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发。解决方案就是前后端通过API进行交互达到相对独立且松耦合。Swagger就是这样的一个API框架，Swagger支持多种语言 如：Java，PHP等，它号称是世界上最流行的API框架！
2、整合前可能遇到的问题
1、
导入好依赖jar包之后，使用注解说找不到之类的问题，如遇到，请参考：所有Intellij IDEA Cannot Resolve Symbol XXX问题的解决方法汇总
2、
版本问题，SpringBoot的版本很多，被集成的框架版本也很多，可能版本高一点或者低一点就可能出现各种bug，这是集成其他框架的通病，这里得注意一下。如果运行出现一些什么bug，如果对SpringBoot底层原理不是很了解的可以先百度谷歌一下，找不到建议不妨换个SpringBoot的版本！
3、SpringBoot集成Swagger
注意：jdk 1.8以上才能运行swagger2
1、
导入两个jar包依赖
<!-- 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>2、
要想使用Swagger，必须编写一个配置类来配置 Swagger，这里的配置类如下
此代码由Java架构师必看网-架构君整理
@Configuration //说明这是一个配置类
@EnableSwagger2// 该注解开启Swagger2的自动配置
public class SwaggerConfig { //随便的一个类名
}3、
这个时候已经算是初步整合完毕了，启动项目可访问http://localhost:8080/swagger-ui.html 可以看到swagger的界面，如下；
4、配置Swagger
不管是Spring Boot整合还是SpringMVC整合Swagger都基本类似，重点就在于配置Swagger，它的精髓所在就在于配置，这很关键。我们从下图来全局看看Swagger的四部分重点布局：
4.1、Swagger四部分布局
Swagger实例Bean是Docket，所以必须通过配置Docket实例来配置Swaggger。
第一部分--API分组：如果没有配置分组默认是default。通过Swagger实例Docket的groupName()方法即可配置分组
第二部分--基本描述：可以通过Swagger实例Docket的apiInfo()方法中的ApiInfo实例参数配置文档信息
第三部分--请求接口列表：在组范围内，只要被Swagger2扫描匹配到的请求都会在这里出现。
第四部分--实体列表：只要实体在请求接口的返回值上（即使是泛型），都能映射到实体项中！
第四部分注意：并不是因为@ApiModel注解让实体显示在Models列表里，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。前者为类添加注释，后者为类属性添加注释。
4.2、第二部分：API基本信息
先从第二部分开始分析，这样分析对理解第一部分比较有帮助。
@Configuration
@EnableSwagger2
@ComponentScan("com.yichun.swagger_boot_demo.controller")
public class SwaggerConfig {
@Bean
public Docket docker(){
// 构造函数传入初始化规范，这是swagger2规范
return new Docket(DocumentationType.SWAGGER_2)
//apiInfo： 添加api详情信息，参数为ApiInfo类型的参数，这个参数包含了第二部分的所有信息比如标题、描述、版本之类的，开发中一般都会自定义这些信息
.apiInfo(apiInfo())
.groupName("yichun123")
//配置是否启用Swagger，如果是false，在浏览器将无法访问，默认是true
.enable(true)
.select()
//apis： 添加过滤条件,
.apis(RequestHandlerSelectors.basePackage("com.yichun.swagger_boot_demo.controller"))
//paths： 这里是控制哪些路径的api会被显示出来，比如下方的参数就是除了/user以外的其它路径都会生成api文档
.paths((String a) ->
!a.equals("/user"))
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("名字：name", "个人链接：http://xxx.xxx.com/", "邮箱：XXX");
return new ApiInfo(
"标题内容", // 标题
"描述内容", // 描述
"版本内容：v1.0", // 版本
"链接：http://terms.service.url/", // 组织链接
contact, // 联系人信息
"许可：Apach 2.0 ", // 许可
"许可链接：XXX", // 许可连接
new ArrayList<>()// 扩展
);
}
}1、分析
2、RequestHandlerSelectors过滤
点进RequestHandlerSelectors源码，分析如下：
4.3、第一部分：配置API分组
实际上，上面的内容就是一个完整的API组
1、配置一个分组
我们之前说过，如果没有配置分组默认是default。通过Swagger实例Docket的groupName()方法即可配置分组，代码如下：
此代码由Java架构师必看网-架构君整理
@Bean
public Docket docket2(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 配置基本API信息
.groupName("hello") // 配置分组
// 省略配置....
}2、如何配置多个分组
很简单，配置多个分组只需要配置多个docket即可，代码如下：
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("组一")
// 省略配置....
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("组二")
// 省略配置....
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("组三")
// 省略配置....
}4.4、Swagger2的常用注解
讲第三部分和第四部分前，非常有必要先了解swagger2的常用注解，用注解的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！这点也是swagger2的重中之重！
首先我们得知道一点Swagger的所有注解定义在io.swagger.annotations包下。，这里只列出一些常用的注解，如下：
如果要详细了解这些注解可以参考swagger2 注解说明
4.5、第三部分：API请求列表
请求接口列表：在组范围内，只要被Swagger2扫描匹配到的请求都会在这里出现。使用注解能更好的提高阅读性。
4.6、第四部分：API实体列表
之前说过，只要实体在请求接口的返回值上（即使是泛型），都能映射到实体项中！是的，因此我们第一步是先有实体类。
1、
我们先随便创建一个实体类
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("性别")
public String sex;
@ApiModelProperty(value ="用户名",allowableValues = "11,12")
public int name;
}当然@ApiModelProperty注解里有很多属性，也会有许多坑，这里注意一下，本篇文章暂不概述。
2、
只要这个实体在请求接口的返回值上（包括泛型），都能映射到实体项中，所以我们编写代码如下：
@GetMapping("/User2")
public User getUser2(){
return new User();
}效果如下：
本篇文章非常浅显，若有不正之处，欢迎批评指正，感激不尽！
腾讯云开发者
