SpringBoot整合Swagger2|实现在线接口文档
前言
我们知道前后端分离后，不管是做前端还是后端都会接触一些接口文档。作为工作的沟通的某一种 介质,大家按照既定的规定各自开发，对接上线。但是实际开发并非这么顺畅，接口总是不断的变化调整，势必浪费很多精力。特别是前后端集成，前端或者后端无法做到“及时协商、尽早解决”，最终倒是问题集中爆发。
解决方案
实时跟踪最新API、降低集成风险
Swagger 介绍
- 号称世界上最流行的API框架
- Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
- 直接运行，在线测试API
- 支持多种语言 （如：Java，PHP等）
- 官网：https://swagger.io/
SpringBoot集成Swagger
要求: JDK1.8+ 否则Swagger2无法运行
1. 工程创建
创建SpringBoot工程,添加web、swagger依赖。启动项目，确保运行正常。
Swagger2相关依赖
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
完整依赖
<dependencies>
<dependency>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-webartifactId>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>
<dependency>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-testartifactId>
<scope>testscope>
<exclusions>
<exclusion>
<groupId>org.junit.vintagegroupId>
<artifactId>junit-vintage-engineartifactId>
exclusion>
exclusions>
dependency>
dependencies>
2. 新建配置类
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
3. 访问测试
启动项目，浏览器输入：
http://localhost:8080/swagger-ui.html
可以看到Swagger界面，表明配置成功
配置类
3.1 ApiInfo详解
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 配置Swagger Bean实例
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 设置swagger-ui.html页面上的一些元素信息
.apiInfo(apiInfo())
// 是否启用Swagger
// .enable(false)
// 配置扫描接口及API
.select()
// 配置要扫描借口的方式
// basePackage:指定扫描的包 com.xxx.xxx
// any: 全扫描
// none: 不扫描
// withClassAnnotation: 扫描类上的注解 (传递注解class,表示只扫描有该注解的类)
// withMethodAnnotation: 扫描方法上的注解
// 扫描的包路径
.apis(RequestHandlerSelectors.basePackage("com.daobili.controller"))
// 过滤什么路径
// ant: .ant("/api/**") 表示只扫描/api/**开头的的接口
// any: 过滤全部的
// none: 不过滤全部的
// regex: 正则
.paths(PathSelectors.any())
.build();
}
/**
* 配置Swagger详细信息 ApiInfo
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("SpringBoot整合Swagger")
// 描述
.description("SpringBoot整合Swagger，详细信息......")
// 版本号
.version("1.0")
// 作者信息
.contact(new Contact("巴莫", "http://www.taiyangyi.com","[email protected]"))
.build();
}
}
3.2 随环境变化启用Swagger
思考：如何使Swagger只在测试或开发中使用，在生产环境中不使用
- 判断是不是生产环境
- 注入enable
@Configuration
@EnableSwagger2
public class SwaggerConfig2 {
/**
* 配置Swagger Bean实例
* @return
*/
@Bean
public Docket createRestApi(Environment env) {
// 获取项目环境
// 设置要显示的Swagger环境
// 通过springboot环境，判断是否处在自己设定的环境
Profiles of = Profiles.of("dev","test");
boolean flag = env.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否启用Swagger
.enable(flag)
// 配置扫描接口及API
.select()
// 配置要扫描借口的方式
// basePackage:指定扫描的包 com.xxx.xxx
// any: 全扫描
// none: 不扫描
// withClassAnnotation: 扫描类上的注解 (传递注解class,表示只扫描有该注解的类)
// withMethodAnnotation: 扫描方法上的注解
// 扫描的包路径
.apis(RequestHandlerSelectors.basePackage("com.daobili.controller"))
// 过滤什么路径
// ant: .ant("/api/**") 表示只扫描/api/**开头的的接口
// any: 过滤全部的
// none: 不过滤全部的
// regex: 正则
.paths(PathSelectors.any())
.build();
}
/**
* 配置Swagger详细信息 ApiInfo
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("SpringBoot整合Swagger")
// 描述
.description("SpringBoot整合Swagger，详细信息......")
// 版本号
.version("1.0")
// 作者信息
.contact(new Contact("巴莫", "http://www.taiyangyi.com","[email protected]"))
.build();
}
}
application.properties
spring.profiles.active=dev
application-dev.properties 开发环境
server.port=8081
application-prod.properties 生产环境
server.port=8082
3.3 分组
- 多个分组创建多个Docket Bean即可
- 应用：多人分模块开发，每个人都可以创建自己的Bean
![[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-orRwCBs7-1606981049076)(evernotecid://88D0C974-A1DC-476C-A7F4-F07B1FC5B743/appyinxiangcom/29250714/ENResource/p18)]](http://img.e-com-net.com/image/info8/c447bbad58a940089eb9e938b85bd3dc.jpg)
//@Configuration
//@EnableSwagger2
public class SeaggerConfig3 {
@Bean
public Docket docketA(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docketB(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docketC(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
// 配置Swagger Bean实例
@Bean
public Docket docket(Environment env){
// 获取项目环境
// 设置要显示的Swagger环境
// 通过spingboot环境，判断是否处在自己设定的环境
Profiles of = Profiles.of("dev","test");
boolean flag = env.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 分组名字
.groupName("x模块")
// 是否启用Swagger
.enable(flag)
// 配置扫描借口及API
.select()
// 配置要扫描借口的方式
// basePackage:指定扫描的包 com.xxx.xxx
// any: 全扫描
// none: 不扫描
// withClassAnnotation: 扫描类上的注解 (传递注解class,表示只扫描有该注解的类)
// withMethodAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
// 过滤什么路径
// ant: .ant("/api/**") 表示只扫描/api/**开头的的接口
// any: 过滤全部的
// none: 不过滤全部的
// regex: 正则
.paths(PathSelectors.any())
.build();
}
/**
* 配置Swagger详细信息 ApiInfo
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("SpringBoot整合Swagger")
// 描述
.description("这是xxx项目的Restful Api文档")
// 版本号
.version("1.0")
// 作者信息
.contact(new Contact("巴莫", "http://www.taiyangyi.com","[email protected]"))
.build();
}
}
4. 实体配置
- @ApiModel为类添加注释
- @ApiModelProperty为类属性添加注释
@ApiModel(description = "用户类")
public class User {
@ApiModelProperty("用户id")
private Long id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("用户地址")
private String address;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getAddress() {
return address;
}
public void setAddress(String address) {
this.address = address;
}
}
5. Controller
快速搭建
@Api("用户管理接口")
@RestController
@RequestMapping("/user")
public class UserController {
@ApiOperation("根据id查询用户")
@ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99")
@GetMapping("/")
public User getUserById(Long id) {
User user = new User();
user.setId(id);
return user;
}
@ApiOperation("根据id更新用户名")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99"),
@ApiImplicitParam(name = "username", value = "用户名", defaultValue = "bamaw")
})
public User updateUsernameById(String username, Long id) {
User user = new User();
user.setId(id);
user.setUsername(username);
return user;
}
@ApiOperation("根据id更新用户信息")
@PutMapping("/{id}")
public User updateUserById(@RequestBody User user) {
return user;
}
@ApiOperation("添加用户")
@PostMapping("/")
public User addUser(@RequestBody User user) {
return user;
}
@ApiOperation("根据id删除用户")
@DeleteMapping("/{id}")
public void deleteUserById(@PathVariable Long id) {
}
@GetMapping("/hello")
public String hello(String name) {
return "hello " + name;
}
}
5. 注解详解
Swagger的所有注解定义在io.swagger.annotations包下
@Api
- tags: 标记 标记可用于逻辑分组，也就是不同的Controller，在swagger文档中会聚合到一起
@ApiOperation
- value: 方法说明
- notes: 方法详细描述
@ApiParam 对象类型参数，文件类型参数
- name: 设置参数名，等同@RequestParam功能
- value: 参数详细描述
- required: 参数是否必须 [ true / false ]
@ApiImplicitParams
- value: ApiImplicitParam数组
@ApiImplicitParam
- name: 设置参数名，等同@RequestParam功能
- value: 参数详细描述
- dataType: 参数的数据类型
- paramType: 上传参数类型
- path 以地址的形式提交数据
- query 直接跟参数完成自动映射赋值
- body 以流的形式提交 仅支持POST
- header 参数在request headers 里边提交
- form 以form表单的形式提交 仅支持POST
@ApiModel
- value: 说明
- description: 详细描述
@ApiModelProperty
- value: 说明
- example: 样例，例子
代码示例
本教程配套仓库
- Github: https://github.com/bamaw/springboot2.x-examples.git