SpringBoot 框架（九）—— SpringBoot 集成 Swagger
SpringBoot 集成 Swagger
- 一、SpringBoot 集成 Swagger
-
- 1.1 创建项目并集成Swagger
-
- 1.1.1 创建项目
- 1.1.2 导入Swgger依赖
- 1.1.3 编写Config类
- 1.2 Swagger 相关配置
-
- 1.2.1 配置是否启动Swagger
- 1.2.2 配置Swagger 扫描接口
- 1.2.3 配置过滤器
- 1.2.4 配置Swagger 文档分组
- 1.3 Swagger 配置 Models
-
- 1.3.1 默认配置Models
- 1.3.2 自定义配置Models
- 1.4 Swagger 测试
一、SpringBoot 集成 Swagger
1.1 创建项目并集成Swagger
1.1.1 创建项目
1.1.2 导入Swgger依赖
进入Maven官网，搜索springfox swagger
导入上述两个依赖
<!-- springfox-swagger UI -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
1.1.3 编写Config类
编写一个SwaggerConfig 作为SpringBoot中Swagger的配置
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
@EnableSwagger2直接的作用是开启Swagger2
编写完成后，启动项目，然后在浏览器访问http://localhost:8080/swagger-ui.html，即可进入到Swagger文档界面
自定义Swagger文档界面，在SwaggerConfig类中配置Swagger文档界面的相关信息
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
/**
* 配置Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
/**
* 配置 Swagger 信息的 apiInfo
*/
private ApiInfo apiInfo(){
Contact contact = new Contact("痞猫尤加利的博客","https://blog.csdn.net/baidu_27414099","[email protected]");
return new ApiInfo(
"Swagger Document",
"Document For Swagger Demo",
"v1.0",
"https://blog.csdn.net/baidu_27414099",
contact,
"Apache 2.0",
"http://www/apache.org/icenses/LICENSE-2.0",
new ArrayList()
);
}
}
重启项目，再次在浏览器中访问，相关位置的修改已被修改
1.2 Swagger 相关配置
1.2.1 配置是否启动Swagger
在SwaggerConfig 类中可以配置是否启动Swagger
/**
* 配置Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false); //配置是否启动Swagger
}
- enable：false，则不启动Swagger，无法再浏览器中访问
true，则启动Swagger
配置完成，再次启动后在浏览器访问则会出现以下界面
1.2.2 配置Swagger 扫描接口
/**
* 配置Swagger 的 Docket 的 Bean 实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors：配置要扫描的接口
.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
//.paths()
.build();
}
RequestHandlerSelectors：配置要扫描的接口，有如下选项：
RequestHandlerSelectors.basePackage()：基于某一个包扫描，如下示例：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors：配置要扫描的接口
.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
.build();
}
配置后再次启动并访问，则出现以下界面，只有配置扫描的包下的接口会出现在界面中
2. RequestHandlerSelectors.withClassAnnotation()：扫描类上的注解，如下示例：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors：配置要扫描的接口
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.build();
}
上面的配置就只会扫描有RestController的类
RequestHandlerSelectors.withMethodAnnotation()：扫描方法上的注解，如下示例：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors：配置要扫描的接口
.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
.build();
}
上面的配置就只会扫描有GetMapping的方法
RequestHandlerSelectors.any()：扫描全部，如下示例：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors：配置要扫描的接口
.apis(RequestHandlerSelectors.all())
.build();
}
RequestHandlerSelectors.none()：都不扫描，如下示例：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors：配置要扫描的接口
.apis(RequestHandlerSelectors.none())
.build();
}
1.2.3 配置过滤器
Swagger 配置过滤器用paths()，如下示例：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.paths(PathSelectors.ant("/test/**"))
.build();
}
paths需要一个PathSelectors类型的参数，PathSelectors有如下选择
(PathSelectors.ant("")：如下表示只扫描并通过带有"/test/"的所有请求
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.paths(PathSelectors.ant("/test/**"))
.build();
}
PathSelectors.regex()：表示利用正则表达式进行匹配PathSelectors.any()：表示所有都通过PathSelectors.none()：表示所有都不通过
1.2.4 配置Swagger 文档分组
配置Swagger 用groupName()，如下示例中，配置了多个分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组3");
}
@Bean
public Docket docket4(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("分组4");
}
启动项目并在浏览器中访问Swagger，得到如下界面，可以看到有四个分组可以选择
1.3 Swagger 配置 Models
1.3.1 默认配置Models
创建一个实体类UsersModel类如下
public class UsersModel {
public int id;
public String name;
public int age;
public String sex;
}
在TestController类中新增一个方法，用于返回UsersModel示例
@GetMapping(value = "/users")
public UsersModel usersModel(){
return new UsersModel();
}
启动项目再次访问Swagger文档，如下
1.3.2 自定义配置Models
① 给实体类和字段上添加注释，如下
@ApiModel("客户实体类")
public class UsersModel {
@ApiModelProperty("编号")
public int id;
@ApiModelProperty("姓名")
public String name;
@ApiModelProperty("年龄")
public int age;
@ApiModelProperty("性别")
public String sex;
}
@ApiModel("客户实体类")：给实体类添加注释@ApiModelProperty("编号")：给实体类的字段添加注释
再次启动并访问，则出现以下界面，可以看大实体类和对应字段都有对应的说明，能够方便查看和使用
②给方法添加注释
在方法上添加@ApiOperation()即可给该方法添加相应注释，如下示例，在TestController中再添加一个方法
@PostMapping(value = "/test1")
@ApiOperation("test1方法")
public String test1(){
return "tes1";
}
结果如下
给方法参数添加注释
在方法上添加@ApiParam()即可给该方法添加相应注释，如下示例，在TestController中再添加一个方法
@PostMapping(value = "/test2")
@ApiOperation("test2方法")
public String test2(@ApiParam("str2参数注释")String str2){
return "test2";
}
结果如下
1.4 Swagger 测试
Swagger 可以利用浏览器直接测试接口，方便调试和查看错误
在Swagger 文档界面，点击Try it out，进入到测试界面
在测试界面，输入测试参数点击Excecute即可测试
测试结果如下，测试结果中包含测试返回信息，以及报错信息
