SpringBoot整合Swagger2

一、Swagger简介

​ Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，被广泛应用于前后端分离项目中，用来降低前后端开发人员的沟通成本，因为Swagger可以根据后端接口的设计动态的生成restful风格的API文档供前端开发人员的使用。除此之外，Swagger还提供了接口测试功能，使得开发人员可以方便的测试接口的可用性。有了Swagger以后，开发人员再也不用维护接口文档了。

​ Swagger目前应用最多的版本就是Swagger2，下面说明SpringBoot如何整合Swagger2

二、SpringBoot整合Swagger2

1、在项目中引入下面两个jar包

<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>

2、创建一个Swagger的配置类

​ 并使用@EnableSwagger2注解开启Swagger2的支持

//表明是一个配置类
@Configuration
//开启Swagger2的支持
@EnableSwagger2
public class SwaggerConfig {
}

​ 此时就可以在项目中利用默认配置使用Swagger了，启动项目后，访问 http://localhost:8080/swagger-ui.html/ 即可得到一份在线API文档，如下：

​ 此时文档中的信息都是默认值，一般情况下我们需要修改其中的信息，如下。

3、自定义Swagger文档信息

​ 向容器中加入一个Docket bean，替换掉默认使用的Docket，它是Swagger的核心bean，可以帮助我们自定义文档中的信息。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
//DocumentationType.SWAGGER_2是DocumentationType类提供的一个常量
//表示我们使用的Swagger文档类型为SWAGGER_2
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//如果我们需要自定义文档信息，需要调用apiInfo方法，传入一个ApiInfo对象，此对象用来封装文档中显示的相关信息
//设置文档所属的组名
docket.apiInfo(apiInfo())
.groupName("groupLy");
return docket;
}

private ApiInfo apiInfo(){
//Contact用来封装联系人（作者）的相关信息，只能通过构造器为各属性赋值
//public Contact(String name, String url, String email)
//分别是作者的姓名、主页和邮箱
Contact contact = new Contact("deng","https://me.csdn.net/blog/m0_46159545","7840@qq.com");
//ApiInfo没有set方法，只能通过构造方法为各个属性赋值
//public ApiInfo(
//		String title, 文档的标题
//		String description, 文档的描述
//		String version, 文档的版本
//		String termsOfServiceUrl,文档的服务商网址
//		Contact contact, 联系人信息
//		String license, 许可证，一般使用Apache 2.0
//		String licenseUrl, 许可证地址，一般使用
//						http://www.apache.org/licenses/LICENSE-2.0
//		Collection<VendorExtension> vendorExtensions，
//											  一般使用newArrayList()
//)
ApiInfo apiInfo = new ApiInfo(
"Boss朴的SwaggerAPI文档",
"这是我的第一份SwaggerAPI文档",
"1.0",
"https://me.csdn.net/blog/m0_46159545",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
return apiInfo;
}
}

​ 经过上面的配置，重新启动项目，访问 http://localhost:8080/swagger-ui.html/，得到如下的页面：

​ 这样就完成了API文档信息的自定义，但是SpringBoot默认的同德errorAPI也是默认显示出来的，我们一般情况下不希望出现这类API的信息，那么就涉及到如何设置API的显示了。

4、设置API的扫描范围

​ 我们可以使用Docket对象来设置文档中显示那些API接口信息，将第三步中docket()修改如下：

@Bean
public Docket docket(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.apiInfo(apiInfo())
.groupName("groupLy")
//获得ApiSelectorBuilder对象
.select()
//设置ApiSelector的构建规则
//有apis和paths两个方法可以使用：
//apis(Predicate<RequestHandler> selector),可以调用下面五个方法获得									Predicate<RequestHandler>对象
//RequestHandlerSelectors.any()：全部构建，只要是API就构建，													     默认使用这种方式
//RequestHandlerSelectors.none()：全部不构建
//RequestHandlerSelectors.basePackage()：构建指定包下的所有															  API
//RequestHandlerSelectors.withClassAnnotation()：仅构建带														 有指定（类注解）的API，
//相当于在@Controller等注解的基础上同时要求必须拥有指定																	  的类注解
//RequestHandlerSelectors.withMethodAnnotation()：仅构建带														有指定（方法注解）的API，
//相当于在@GetMapping等注解的基础上同时要求必须拥有指定																	的方法注解
//paths(Predicate<String> selector),可以调用下面四个方法获得											Predicate<String>对象
//PathSelectors.any():构建所有请求路径的API
//PathSelectors.none()：所有路径的API都不构建
//PathSelectors.ant(String pattern):仅构建指定格式的API
//PathSelectors.regex()：仅构建正则匹配的API
.paths(PathSelectors.ant("/hello"))
//构建ApiSelector
.build();
return docket;
}

​ 此时再次访问Swagger文档，可以看到仅有/hello的API被显示：

5、根据环境控制Swagger的开启

​ 在实际开发中往往会有这样的需求，我们希望Swagger只有在dev和test环境下能使用，在prod环境下不能使用。为了解决这个问题，就需要控制Swagger的开启和关闭，在第四步的基础上继续修改：

//获取Environment对象
@Bean
public Docket docket(Environment environment){
//创建"dev","test"的Profiles对象
Profiles profiles = Profiles.of("dev","test");
//校验当前环境是否是"dev"或者"test"环境
boolean flag = environment.acceptsProfiles(profiles);
Docket docket = new Docket(DocumentationType.SWAGGER_2);
//将flag作为是否开启Swagger的条件
docket.enable(flag)
.apiInfo(apiInfo())
.groupName("groupLy")
.select()
.paths(PathSelectors.ant("/hello"))
.build();
return docket;
}

​ 在SpringBoot配置文件中模拟不同的环境进行测试：

spring:
profiles:
active: prod

---
spring:
profiles: dev
server:
port: 8001

---
spring:
profiles: prod
server:
port: 8002

​ 在生产环境下，Swagger页面正常显示；而在prod环境下，得到如下页面：

6、Swagger的分组设置

​ 在实际开发中，后端API的开发往往是多人协同开发的，再使用Swagger扫描API时，每个人负责扫描每个人开发的API，这就产生了API分组的概念，一个组对应一套API。

​ 在Swagger中，一个Docket实例bean就代表一个组，多人协同开发时，各自注入各自的Docket实例即可实现API分组，但是要注意bean的name不能相同，否则Spring会报错。另外可以使用Docket中的groupName（String）方法设置该组的组名，用来区分不同的组。

​ 每个人都可以通过Docket自定义API页面和API扫描范围等的设置。

@Bean
public Docket docketA(Environment environment){
Profiles profiles = Profiles.of("dev","test");
boolean flag = environment.acceptsProfiles(profiles);
Docket docket = new Docket(DocumentationType.SWAGGER_2);
docket.enable(flag)
.apiInfo(apiInfo())
.groupName("A")
.select()
.paths(PathSelectors.ant("/hello"))
.build();
return docket;
}

@Bean
public Docket docketB(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}

@Bean
public Docket docketC(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}

​ 此时的Swagger页面变为了：

​ 切换为B组，则显示B组的API，C组同理。

7、SwaggerAPI文档注释

​ 在Swagger中，如果我们可以在后端接口上使用@Api、@ApiOperation和@ApiParam注解来对控制器类、接口方法以及方法参数进行注释，并且在后端model类上、属性上使用@ApiModel，@ApiModelProperty进行注释，这样得到的API文档可读性更高，如下：

@Api(description = "讲师管理")
@RestController
@RequestMapping("/edu/teacher")
public class EduTeacherController {
@Autowired
private EduTeacherService service;

@ApiOperation("查询所有讲师")
@GetMapping("/findAll")
public Result findAll(){
List<EduTeacher> list = service.list(null);
return Result.ok().data("items", list);
}
}

@ApiModel("统一的json返回格式")
public class Result {
@ApiModelProperty(value = "是否成功返回",example = "true")
private Boolean success;
@ApiModelProperty(value = "返回状态码",example = "20000")
private Integer code;
@ApiModelProperty(value = "返回消息",example = "返回数据成功")
private String message;
@ApiModelProperty(value = "返回数据",example = "{k1:v1,k2:v2}")
private Map<String,Object> data = new HashMap<>();