SpringBoot学习之整合Swagger
Swagger介绍
1.什么是Swagger
作为后端程序开发,我们多多少少写过几个后台接口项目,不管是编写手机端接口,还是目前比较火热的前后端分离项目,前端与后端都是由不同的工程师进行开发,那么这之间的沟通交流通过接口文档进行连接。但往往伴随很多问题,后端程序员认为编写接口文档及维护太花费时间精力,前端的认为接口文档变动更新不及时,导致程序之间相互调用出行问题。那么能简化接口文档的编写直接自动生成吗?当然能!如是乎Swagger这种接口文档在线自动生成工具便孕育而生。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
2.Swagger优点
- 代码变,文档变。只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性。
- 跨语言性,支持 40 多种语言。
- Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程。
- 还可以将文档规范导入相关的工具(例如 Postman、SoapUI), 这些工具将会为我们自动地创建自动化测试。
SpringBoot中整合Swagger
1.基础环境构建
首先搭建一个基础的SpringBoot项目,导入以下Swagger启动器
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter<artifactId>
<version>3.0.0</version>
</dependency>
编写一个用于测试的controller
@RestController
public class HelloController {
@PostMapping(value = "/hello")
public String hello(){
return "hello";
}
}
编写Swagger的配置类
@Configuration
@EnableOpenApi
public class SwaggerConfig {
}
运行启动输入地址:http://localhost:8080/swagger-ui/index.html
可以看到Swagger接口文档页面,说明基本配置环境成功!
注意事项:
Swagger3.0版本的地址是http://localhost:8088/swagger-ui/index.html,2.x版本中访问的地址的为http://localhost:8088/swagger-ui.html
2.配置Swagger
配置Swagger首先需要构建其Bean实例 Docket
对象,在刚刚创建的SwaggerConfig
配置类中创建一个Docket
@Bean
public Docket docket(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo());
}
Docket(DocumentationType.OAS_30)
,我们这里选择的参数是 DocumentationType.OAS_30
,这是一个Swagger实例的接口文档版本,我们这里是3.0,所以选择用 OAS_30
,其他的类型还有如下几种,分别对应着Swagger历史版本
public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
public static final DocumentationType OAS_30 = new DocumentationType("openApi", "3.0");
构建Docket需要创建 ApiInfo
实例
private ApiInfo apiInfo(){
// 作者信息
Contact contact = new Contact("TIOXY", "https://www.cnblogs.com/tioxy/", "1369773052@qq.com");
return new ApiInfo(
"Tioxy的接口文档",
"项目描述",
"1.0",
"https://www.cnblogs.com/tioxy/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
ApiInfo
主要作用是构建我们接口文档的页面显示的基础信息,展示如下位置
3.配置扫描接口及开关
构建Docket时通过 select()
方法配置扫描接口。Docket的完整代码如下:
@Bean
public Docket docket(Environment environment){
// 设置显示的Swagger环境
Profiles dev = Profiles.of("dev");
// 获取项目环境
boolean flag = environment.acceptsProfiles(dev);
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
// 配置Api文档分组
.groupName("TIOXY")
// enable()是否启用Swagger,默认是true
.enable(flag)
.select()
// RequestHandlerSelectors,配置要扫描接口的方式
// basePackage指定要扫描的包
// any()扫描所有,项目中的所有接口都会被扫描到
// none()不扫描
// withClassAnnotation()扫描类上的注解
// withMethodAnnotation()扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.tioxy.controller"))
// paths()过滤某个路径
.paths(PathSelectors.any())
.build();
}
groupName("TIOXY")
:表示此Docket实例的名字,也就是接口文档页面右上角选择的实例名,实际开发中我们是多人开发,对应的就是多个Docket实例enable(flag)
:enable()
是否启用Swagger,默认是true
我们这里使用的是动态的配置是否启用Swagger,通过 Environment
来获取此时运行的项目环境名称,如果是 dev
,则定义一个flag,来动态的设置是否启用
4.实体类配置
新建一个User实体类
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中:
@RequestMapping("/getUser")
public User getUser(){
return new User();
}
5.常用注解
我们也可以在接口上添加注释说明,方便我们在接口文档中解释说明接口的信息,例如接口的作用、参数说明等,方便调用者使用
Swagger注解 | 简单说明 |
---|---|
@Api(tags = "xxx模块说明") | 作用在模块类上 |
@ApiOperation("xxx接口说明") | 作用在接口方法上 |
@ApiModel("xxxPOJO说明") | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = "xxx属性说明",hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam("xxx参数说明") | 作用在参数、方法和字段上,类似@ApiModelProperty |
文章参考
狂神说Java系列之SpringBoot整合Swagger学习笔记