SpringBoot整合Swagger2
SpringBoot整合Swagger2
一、swagger简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。 作用：
- 接口的文档在线自动生成。
- 功能测试。
二、基本配置
1、pom.xml
springfox-swagger2
springfox-swagger-ui
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.5.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>org.lc</groupId>
<artifactId>swagger2</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger2</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2、swagger配置文件
@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
//这里properties中的配置的swagger.enable和havingValue相等这个配置文件才会生效
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Config {
/**
*构建swagger摘要
* @return
*/
@Bean
Docket docket() {
// 选择文本类型为SWAGGER_2
return new Docket(DocumentationType.SWAGGER_2)
.select()
// 指定controller所在的包
.apis(RequestHandlerSelectors.basePackage("org.lc.swagger2.controller"))
// 指定包下的所有路径生成文档
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
// 文档描述信息
.description("这是接口文档描述信息")
// 标题
.title("这是项目标题")
// 联系信息
.contact(new Contact("lc", "www.louchen.top", "421192425@qq.com"))
// 版本
.version("v0.0.1")
// 许可证
.license("apache2.0")
.build());
}
}
3、是否开启swagger配置
swagger.enable=true
4、实体描述
@Getter
@Setter
@ToString
@ApiModel(value = "用户实体类",description = "用户信息描述")
public class User {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String name;
@ApiModelProperty(value = "用户地址")
private String address;
}
5、接口描述
@RestController
//接口上的描述
@Api(tags = "用户数据接口")
public class UserController {
/**
* 这里需要指定的请求方式 否则swagger会启用所有方法类型调用
* @param id
* @return
*/
// 接口方法上的描述
@ApiOperation(value = "查询用户",notes = "根据用户id查询用户")
// 接口参数上的描述
// 这里的name为参数名，value为对该参数的解释，required只是对swagger的约束表示必填，默认值为11
@ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "11")
@GetMapping("/user")
public User getUserById(Integer id) {
User user=new User();
user.setId(id);
return user;
}
@ApiOperation(value = "删除用户",notes = "根据用户id删除用户")
@ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "22")
// 设置响应的状态码的描述信息
@ApiResponses({
@ApiResponse(code = 200, message = "删除成功"),
@ApiResponse(code = 500, message = "删除失败")
})
@DeleteMapping("/user/{id}")
public void deleteById(@PathVariable("id")Integer id){
System.out.println("deleteById:"+id);
}
@ApiOperation(value = "更新用户",notes = "根据用户id更新用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",value = "用户名",required = true,defaultValue = "lc"),
@ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "1")
})
// 表示忽略此接口生成在swagger中
// @ApiIgnore
@PutMapping("/user")
public User updateUserById(String username,Integer id){
User user=new User();
user.setId(id);
user.setName(username);
return user;
}
@ApiOperation(value = "添加用户",notes = "添加用户信息")
@PostMapping("/user")
public User addUser(@RequestBody User user){
return user;
}
}
6、swagger注解介绍
@Api：可设置对控制器的描述-
@ApiOperation：: 可设置对接口方法的描述
@ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
@ApiImplicitParams: 用于描述接口的非对象参数集。
@ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。
@ApiImplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
需要注意的是，@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger2 框架内必填，抛弃了 Swagger2 ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略。
@ApiModel:可设置接口相关实体的描述
@ApiModelProperty: 可设置实体属性的相关描述。
7、在 Security 中的配置
如果我们的 Spring Boot 项目中集成了 Spring Security，那么如果不做额外配置，Swagger2 文档可能会被拦截，此时只需要在 Spring Security 的配置类中重写 configure 方法，添加如下过滤即可：
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring()
.antMatchers("/swagger-ui.html")
.antMatchers("/v2/**")
.antMatchers("/swagger-resources/**");
}
如此之后，Swagger2 文件就不需要认证就能访问了