SpringBoot 集成 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","1234567@qq.com");
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即可测试
测试结果如下,测试结果中包含测试返回信息,以及报错信息