Spring Boot(十五)--------Swagger介绍及集成
25、Swagger
25.1 前言
- 前后端分离:Vue+SpringBoot
- 后端时代:前端只需要管理静态页面:html、css、js。后端通过模板引擎JSP重写,后端是主力
25.1.1 前后端分离时代
- 前端:前端控制层,视图层;伪造后端数据,json。不需要后端,前端功能仍旧能跑起来
- 后端:后端控制层(Controller),服务层,数据访问层
- 前后端通过API进行交互,前后端相对独立且松耦合
25.1.2 产生的问题
- 强后端集成联调,前端或后端无法做到”及时协商,尽早解决“,最终导致问题集中爆发
25.1.3 解决方案
- 首先定义提纲,并实时跟踪最新的API,降低集成风险
- 早些年:指定word计划文档
- 前后端分离
- 前端测试后端接口:postman
- 后端提供接口,需要实时更新最新的消息及改动
25.2 Swagger
- 号称世界上最流行的API框架
- Restful Api文档在线自动生成器,API文档和API定义同步更新
- 直接运行,在线测试API
- 支持多种语言(如:Java,PHP等)
- 官网:API Documentation & Design Tools for Teams | Swagger
25.3 SpringBoot集成Swagger
- 导入
springfox-swagger2
和springfox-swagger-ui
的jar包 - 使用Swagger时,需要使用jdk1.8+,否则swagger2无法运行
- 新建一个SpringBoot项目,导入web依赖
- 3.0版本之前
<!--2.9.2版本-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 3.0版本之后,springboot版本2.5.6
<!--3.0.0版本-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
- 编写
HelloController
,测试是否运行成功
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
- 应用主类增加注解
@EnableOpenApi
@SpringBootApplication
@EnableOpenApi
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
- 测试访问网址:
http://localhost:8080/swagger-ui/index.html
或http://localhost:8080/swagger-ui/
,可以看到swagger页面
25.4 配置Swagger
-
新建一个
SwaggerConfig
类,并且加上注解@Configuration
-
Swagger的
Bean
实例是Docket
,所以通过配置Docket
实例来配置Swagger,可以通过apiInfo()
属性配置文档信息
@Configuration
public class SwaggerConfig {
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo());
}
//配置Swagger信息apiInfo()
private ApiInfo apiInfo(){
return new ApiInfo(
//标题
"zmt的Swagger Api文档",
//描述
"作者描述",
//版本
"1.0",
//服务条款url
"https://www.baidu.com",
//作者信息
new Contact("zzz", "https://www.baidu.com", "123@qq.com"),
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
- 重启项目,访问
http://localhost:8080/swagger-ui/
,看下效果
25.5 配置扫描接口
- 构建
Docket
时通过select()
方法配置如何扫描接口
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
//建造者模式
.build();
}
-
重启项目测试,发现只扫描了指定包下的接口
-
除了通过包 路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式
// 根据包路径扫描接口
basePackage(final String basePackage)
// 扫描所有,项目中的所有接口都会被扫描到
any()
// 不扫描
none()
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
- 还可以配置接口扫描过滤
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors 配置要扫描接口的方式
//basePackage 指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
//过滤什么路径,只扫描以/zzz开头的接口路径
.paths(PathSelectors.ant("/zzz/**"))
//建造者模式
.build();
}
- 可选值有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
25.6 配置Swagger开关
- 通过
enable()
方法配置是否启用swagger,如果是false,swagger将不能在浏览器种访问
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
//是否启用swagger
.enable(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
//.paths(PathSelectors.ant("/zzz/**"))
.build();
}
- 重启项目,可以看到无法浏览器访问swagger
- 如何动态配置,当项目处于dev测试环境时显示swagger,处于pro发布环境时不显示swagger
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//找对包org.springframework.core.env.Profiles;
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//获取项目运行环境
//通过environment.acceptsProfiles(profiles),判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
//实现动态配置swagger
.enable(flag)
.select() .apis(RequestHandlerSelectors.basePackage("com.zmt.swagger.controller"))
//.paths(PathSelectors.ant("/zzz/**"))
.build();
}
- 可以在项目种增加配置文件
#dev测试环境
server.port=8081
#pro生产环境
server.port=8082
#配置哪个环境生效
spring.profiles.active=dev
- 重启测试,启用dev配置文件时,可以访问swagger;启动pro配置文件时,不能访问swagger
25.7 配置API分组
- 如果没有配置分组,默认是
default
。通过groupName()
方法即可配置分组
public class SwaggerConfig {
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
...
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.groupName("zzz")
...
}
- 重启项目查看分组
- 在
SwaggerConfig
中配置多个docket()
方法就可以配置多个分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.OAS_30).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.OAS_30).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.OAS_30).groupName("group3");
}
- 重启项目即可查看
25.8 实体类配置
- 新建一个实体类
public class User {
public String username;
public String password;
}
- 只要这个实体在请求接口的返回值上,都能映射到实体项中
- 在
HelloController
类中写user()
方法
//只要接口返回值中存在实体类,该实体类就会被扫描到swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
- 重启测试
- 还可以给实体类加文档注释
//给实体类加文档注释
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
- 重启测试
- 不是因为加了注解,才让实体类显示在swagger中,而是在接口方法的返回值上出现的实体类才会显示在swagger中。上面的注解只是为了实体类增加注释的
- 也可以给接口配置一些注释
@RestController
public class HelloController {
@ApiOperation("Hello控制接口")
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
//只要接口返回值中存在实体类,该实体类就会被扫描到swagger中
@ApiOperation("User控制接口")
@PostMapping(value = "/user")
public User user(@ApiParam("用户") User user){
return user;
}
}
- 重启测试
25.9 常用注解
- Swagger的所有注解定义在
io.swagger.annotations
包下
Swagger注解 | 简单说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
25.10 Swagger测试接口
- swagger可以用来测试接口
- 输入测试的用户名密码
- 会显示测试接口的结果
25.11 小结
-
Swagger
可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读 -
接口文档实时更新,可以在线测试
-
相较于传统的
Postman
或Curl
方式测试接口,使用swagger
是傻瓜式操作,不需要额外说明文档,不容易出错,只需要录入数据然后点击Execute,如果再配合自动化框架,可以说基本不需要人为操作 -
Swagger是个优秀的工具,现在国内已经有很多的中小型互联网公司都在使用它,相较于传统的要先出Word接口文档再测试的方式,显然这样也更符合现在的快速迭代开发行情。
-
在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时的内存