Swagger
Swagger
学习目标：
- 了解Swagger的作用和概念
- 了解前后端分离
- 在SpringBoot中集成Swagger
Swagger简介
前后端分离
Vue + SpringBoot
- 前端 -> 前端控制层、视图层
- 后端 -> 后端控制层、服务层、数据访问层
- 前后端通过API进行交互
- 前后端相对独立且松耦合
产生的问题
- 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发
解决方案
- 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险
Swagger
- 号称世界上最流行的API框架
- Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
- 直接运行，在线测试API
- 支持多种语言 （如：Java，PHP等）
- 官网：https://swagger.io/
SpringBoot集成Swagger
- 新建一个SpringBoot = web项目
- 导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
-
编写一个Hello工程
-
配置Swagger====>Config
@Configuration @EnableSwagger2 // 开启Swagger2的自动配置 public class SwaggerConfig { } -
访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；
以上是针对springboot2.6.x以下，swagger3.0以下
以下是针对springboot2.6.x以上，swagger3.0
-
新建一个SpringBoot = web项目
-
导入相关依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
配置Swagger
Swagger的bean实例Docket;
Swagger配置扫描接口
Docket.select ()
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,
// RequestHandlerSelectors配置如何扫描接口
// any() 扫描所有，项目中的所有接口都会被扫描到
// none() 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
//withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
// withClassAnnotation(final Class<? extends Annotation> annotation)
// asePackage(final String basePackage) // 根据包路径扫描接口
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//paths() 过滤什么路径
.paths(PathSelectors.ant("/kuang/**"))
.build();
};
配置是否启动Swagger
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) //enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//paths() 过滤什么路径
//.paths(PathSelectors.ant("/kuang/**"))
.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();
}
配置API文档的分组
.groupName("狂神")
如何配置多个分组；多个Docket实例即可
@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");
}
实体类配置
1、新建一个实体类
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
2、只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
@RequestMapping("/user")
public User getUser(){
return new User();
}
3、重启查看测试
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释
