Spring Boot2篇 - 十一、Spring Boot 集成Swagger
十一、Spring Boot 集成Swagger
11.1 Swagger简介
前后端分离
- 前端 -> 前端控制层、视图层
- 后端 -> 后端控制层、服务层、数据访问层
- 前后端通过API进行交互
- 前后端相对独立且松耦合
产生的问题
- 前后端集成,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发
解决方案
- 首先定义schema [ 计划的提纲 ],并实时跟踪最新的API,降低集成风险
Swagger
- 号称世界上最流行的API框架
- Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
- 直接运行,在线测试API
- 支持多种语言 (如:Java,PHP等)
- 官网:https://swagger.io/
11.2 SpringBoot集成Swagger
- 新建一个SpringBoot-web项目
添加Maven依赖
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2 编写HelloController,测试确保运行成功
要使用Swagger,我们需要编写一个配置类SwaggerConfig来配置 Swagger
/**
- @author cVzhanshi
- @create 2021-06-21 14:16
*/
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面
- 说明初步集成成功!
11.3 配置Swagger
Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2);
}通过apiInfo()属性配置文档信息
//配置Swagger的Docket的bean实例
private ApiInfo apiInfo(){//作者信息
Contact contact = new Contact("cvzhanshi", "https://blog.csdn.net/qq_45408390?spm=1011.2124.3001.5343", "cvzhanshi@qq.com");
ApiInfo apiInfo = new ApiInfo(
"cVzhanshi的SwaggerApi文档",
"It's now!",
"v1.0",
"https://blog.csdn.net/qq_45408390?spm=1011.2124.3001.5343",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
return apiInfo;
}
Docket 实例关联上 apiInfo()
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果
11.4 配置扫描接口
构建Docket时通过select()方法配置如何扫描接口
@Bean
public Docket getDocket(){return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("cn.cvzhanshi.swagger.controller"))
.build();
}
重启项目测试,由于我们配置根据包的路径扫描接口,所以我们只能看到一个类
除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口
any() // 扫描所有,项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口除此之外,我们还可以配置接口扫描过滤
@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/cvzhanshi/**"))
.build();
}
可选值还有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
11.5 配置Swagger开关
通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
@Bean
public Docket getDocket(){return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("cn.cvzhanshi.swagger.controller"))
.build();
}
如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
@Bean
public Docket docket(Environment environment) {// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
测试动态配置Swagger
application-dev.properties
server.port=8082
application-prod.properties
server.port=8081
application.properties
spring.profiles.active=prod
application.properties
spring.profiles.active=dev
11.6 配置API分组
如果没有配置分组,默认是default。通过groupName()方法即可配置分组
@Bean
public Docket getDocket(Environment environment){// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean flag = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("cvzhanshi")
...;
}
启动项目查看
如何配置多个分组?配置多个分组只需要配置多个docket即可
@Bean
public Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName(“group1”);
}
@Bean
public Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName(“group2”);
}
@Bean
public Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName(“group3”);
}
设置了分组就能不同的人开发生成不同的api文档
11.7 实体配置
新建一个实体类
@ApiModel(“用户实体”)
public class User {@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中
@RequestMapping(“/getUser”)
public User getUser(){return new User();
}
注:并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释
11.8 常用注解
Swagger的所有注解定义在io.swagger.annotations包下
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
通过添加注解可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读
总结:
1.我们可以通过Swagger给一些比较难理解的属性或者接口, 增加注释信息
2.接口文档实时更新
3.可以在线测试
还没有评论,来说两句吧...