Swagger
1.前后端分离时代
后端团队:后端控制层、服务层、数据访问层
前端团队:前端控制层、视图层
前后端通过API进行交互
前后端分离的项目相对更加独立,松耦合,甚至可以部署在不同的服务器上
2.Swagger简介
①号称世界上最流行的API框架
②RestFul API文档在线生成工具,API文档与API定义同步更新
③直接运行,可以在线测试API接口
④Swagger需要两个Jar包,分别为SpringFox-Swagger2和SpringFox-Swagger2-UI
⑤可以通过伪数据进行在线测试,类似于Postman
//仓库:https://central.sonatype.com/
<dependency>
<groupId>org.thingsboard</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.4</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
3.Spring Boot集成Swagger
步骤操作:
①新建Spring Boot项目
②测试项目是否搭建成功,新建一个请求
@RestController
public class HelloController {
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
③运行项目,访问http://localhost:8080/hello,返回hello即搭建成功
④添加Swagger的两个依赖
⑤集成Swagger2,添加SwaggerConfig
@Configuration //相当于@Component,将此类添加到配置中
@EnableSwagger2 //开启SWagger2
public class SwaggerConfig {
}
⑥测试运行Swagger:访问http://localhost:8081/swagger-ui.html
4.版本冲突问题解决
步骤一: 降低SpringBoot、Swageer版本
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.5.6</version>
<relativePath/>
<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>
步骤二: 添加资源注册器,原因SpringBoot不会自动注册Swagger-ui.html
//重写静态资源映射方法,然后重启项目
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
//注册资源映射器
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}
5.配置Swagger
5.1 配置Swagger的Docker实例
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
//配置Swagger的Docker实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
}
5.2 配置Swagger-ui的apiInfo信息
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
//配置Swagger的Docker实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
//配置Swagger的apiInfo信息
public ApiInfo apiInfo(){
Contact DEFAULT_CONTACT = new Contact("小郭", "", "");
return new ApiInfo(
"小郭的Api文档",
"Api Documentation",
"1.0",
"urn:tos",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
5.3 配置扫描接口信息
Swagger只有一个Docker实例,其中**Docker.select( )通过配合buid( )**提供了扫描接口的配置方式,即select( )和buid( )必须配合使用
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//扫描全部
.apis(RequestHandlerSelectors.any())
//不进行扫描
.apis(RequestHandlerSelectors.none())
//扫描指定包
.apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
//扫描指定类的注解,参数是一个注解的反射对象
.apis(RequestHandlerSelectors.withClassAnnotation(GetMapping.class))
//扫描指定方法的注解
.apis(RequestHandlerSelectors.withMethodAnnotation(GwtCompatible.class))
//过滤全部
.paths(PathSelectors.any())
//不过滤
.paths(PathSelectors.none())
//路径过滤
.paths(PathSelectors.ant("/example/demo2/config/**"))
//正则表达式过滤
.paths(PathSelectors.regex(""))
.build();
}
5.4 配置是否启动Swagger
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否启动Swagger,默认为true
.enable(false)
//扫描接口设置
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
.build();
}
5.5 Swagger根据环境自定义启动
通过外部判断当前环境,在开发环境中使用Swagger,生产环境中自动关闭
①添加生产环境,application-dev.properties并将开发环境切换为生产环境
spring.profiles.active = dev
server.port = 8081
②添加正式环境,application-pro.properties
server.port = 8082
③进行环境判断
@Bean
//Environment用于读取环境配置properties信息
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "pro");
//通过environment.acceptsProfiles判断当前所处环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo2.controller"))
.build();
}
5.6 配置API文档的分组
.groupName("xiaoguo")
5.7 配置多人分组
设置多个Docker实例即可
//默认配置为全部扫描
@Bean
public Docket docketThird(){
return new Docket(DocumentationType.SWAGGER_2).groupName("xiaoguo3");
}
@Bean
public Docket docketSencond(){
return new Docket(DocumentationType.SWAGGER_2).groupName("xiaoguo2");
}
5.8 配置实体类
一、实体类
//用于给实体类添加文档注释
@ApiModel("用户实体类")
public class User {
//用于字段添加文档注释
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
二、扫描实体类
@RestController
public class HelloController {
@GetMapping("User")
//用于给方法添加文档注释
@ApiOperation("用户控制类")
//只要接口中返回值存在实体类,就会被Swagger扫描到
public User user(){
return new User();
}
}