SpringBoot-Swagger集成
初识Swagger
Swagger官网:https://swagger.io/
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
1. 环境搭建
创建SpringBoot-web项目
1. 导入依赖
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
3. 编写HelloWorld
为了保证可以成功运行
4. 配置Swagger配置类
@Configuration // 表明是一个Spring配置类
@EnableSwagger2 // 开启Swagger2的自动配置
public class SwaggerConfig {
}
5. 测试
访问Swagger API 文档
路径：
http://localhost:8080/swagger-ui.html
配置Swagger
编写Swagger配置类
因为 Swagger 的 bean 实例是 Docket，所以我们通过配置Docket实例，并将其加入到Spring容器中来实现对Swagger的配置
SwaggerConfig.java
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
// 配置Swagger的Docket实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()); // 关联配置文档
}
//配置文档信息
private ApiInfo apiInfo(){
//作者信息
Contact DEFAULT_CONTACT = new Contact("作者", "作者链接", "作者邮箱");
return new ApiInfo(
"PenEn's API Documentation", // 标题
"无论遇到什么困难，都要坚信自己前途无量", // 描述
"1.0", // 版本号
"https://www.baidu.com/", // 链接
DEFAULT_CONTACT, // 作者
"Apache 2.0", // apache许可
"http://www.apache.org/licenses/LICENSE-2.0", // 许可链接
new ArrayList()); // 扩展
}
}
创建Swagger实例Docket时 可以通过 ApiInfo配置文档信息
通过链式编程关联ApiInfo
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
重启项目 查看效果
配置扫描接口
Docket通过 .select() 方法来扫描接口
.apis() 扫描哪个接口
.path() 过滤扫描的接口(不扫描)
.buid() 构造
// 配置Swagger的Docket实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() // 配置扫描接口
.apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
.paths(PathSelectors.ant("con.it/*")) // 过滤扫描
.build();
}
apis(RequestHandlerSelectors.basePackage(“com.it.controller”))
表示扫描com.it.controller 下的接口
.paths(PathSelectors.ant(“con.it/*”))
表示过滤扫描 cont.it./*下的接口
apis（）方法中的参数可以是↓
any() : 扫描所有，项目中所有接口都会被扫描
none() : 不扫描接口
withMethodAnnotation(final Class annotation)
通过 方法上 注解来扫描
withClassAnnotation(final Class annotation)
通过 类上 注解来扫描
basePackage(final String basePackage) : 根据包路径扫描接口
path（）方法中的参数可以是↓
any() : 任何请求都扫描
none() : 任何请求都不扫描
regex(final String pathRegex) : 通过正则表达式控制
ant(final String antPattern) : 通过路径来过滤
配置Swagger开关
通过Docket实例 .enable() 方法配置开启或关闭Swagger
配置关闭后 Swagger不能在浏览器中访问
// 配置Swagger的Docket实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
.select() // 配置扫描接口
.apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
// .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
.build();
}
enable（参数） 参数为true表示开启Swagger 可以在浏览器中访问
参数为false 表示关闭Swagger，不可以在浏览器中访问
我们可以动态配置开启或关闭Swagger
例如我们现在的项目 处于 dev 环境 就开启Swagger 处于 pro 环境就关闭Swagger
我们在Resource下添加application-dev.properties 和 application-pro.properties 两个环境
实现方法
// 配置Swagger的Docket实例
@Bean
public Docket docket(Environment environment){ // 需要Environment参数
// 设置要显示Swagger的环境
Profiles profiles = Profiles.of("dev");
// 判断当前是否处于该环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag) //接收flag值来判断是否显示
.select() // 配置扫描接口
.apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
// .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
.build();
}
我们在 application.properties 中配置多环境Profile为 dev
# 设置环境为dev环境
spring.profiles.active=dev
测试发现 如果配置了多环境切换为dev 则正常显示Swagger Api页面
如果没有配置 就会显示
配置Swagger API 分组
通过Droket实例.groupName() 来配置分组
默认为default
// 配置Swagger的Docket实例
@Bean
public Docket docket(Environment environment){ // 需要Environment参数
// 设置要显示Swagger的环境
Profiles profiles = Profiles.of("dev");
// 判断当前是否处于该环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("佩恩") // 分组名字为 佩恩
.enable(flag) //接收flag值来判断是否显示
.select() // 配置扫描接口
.apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
// .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
.build();
}
可以重启项目访问swagger页面查看效果
如何配置多个分组
配置多个分组 我们只需要在Spring容器中多添加几个Docket实例就好了
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
// 配置Swagger的Docket实例
@Bean
public Docket docket(Environment environment){
Profiles profiles = Profiles.of("dev");
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("佩恩")
.enable(flag)
.select() // 配置扫描接口
.apis(RequestHandlerSelectors.basePackage("com.it.controller")) // 需要扫描的包
// .paths(PathSelectors.ant("con.it/*")) // 过滤扫描
.build();
}
重启项目 查看效果
实体配置
1. 新建实体类
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
private String name;
@ApiModelProperty("密码")
private String password;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
如果想让SwaggerAPI页面识别到这个bean 也就是在页面的Model下能看到 ，我们只需要将这个User 通过Controller 返回出去就OK
@GetMapping("/user")
@ResponseBody
public User user(){
return new User();
}
重启后访问页面发现
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释
@Api(tags = "xxx模块说明") 作用在模块类上
@ApiOperation("xxx接口说明") 作用在接口方法上
@ApiModel("xxxPOJO说明") 作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)
作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明") 作用在参数、方法和字段上，
类似@ApiModelProperty
我们可以在Controller中配置一些注释
@PostMapping("/user1")
@ResponseBody
@ApiOperation("测试返回User")
public User user1(@ApiParam("User实体类") User user){
return user;
}