SpringBoot集成Swagger2的方法
作者:Tom-shushu 时间:2023-11-26 13:15:42
一、是什么
当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成。在这种开发模式下,维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式。
二、为什么要使用它
1、代码变更,文档跟着代码变、只需要少量的注解Swagger就可以根据代码自动的生成API文档,很好的保证了文档的实时性。
2、跨语言,Swagger支持40多种语言。
3、Swagger UI 呈现出来的是一份可以交互的API文档,我们可以直接在文档页面尝试API的调用,省去了准备复杂的调用参数的过程。
4、还可以将文档规范导入相关的工具里面(例如:Postman、SoapUI)、这些工具将会为我们自动地创建自动化测试。
三、怎么用
1、在项目pom.xml里面加入Swagger2相关的依赖
<!--swagger2配置-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
2、新建Swagger2的配置类
package com.zhouhong.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @ClassName: Swagger2
* @Description:
* @Author: 周红
* @NickName: Tom-shuhu
* @Date: Created in 2020/12/15
**/
@Configuration
@EnableSwagger2
public class Swagger2 {
// http://localhost:8088/swagger-ui.html 原路径
// http://localhost:8088/doc.html 原路径
//配置swagger2核心配置
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2) //指定api类型位swagger2
.apiInfo(apiInfo()) //用于定义api文档汇总信息
.select().apis(RequestHandlerSelectors
.basePackage("com.zhouhong.controller")) //指定生成文档的controller
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Tom-shushu 的项目接口api") //文档标题
.contact(new Contact("周红", //作者
"www.zhouhong.icu",
"15249239025@163.com")) //联系人
.description("Tom-shushu 的项目api接口")//详细信息
.version("1.0.0")//文档版本号
.termsOfServiceUrl("www.zhouhong.icu")//网站地址
.build();
}
}
文档配置说明:
a.为任何接口生成API文档,这种方式不必在接口方法上加任何注解,方便的同时也会因为没有添加任何注解所以生成的API文档也没有注释,可读性不高。
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为任何接口生成API文档
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
b.为当前配置的包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.troila"))
c.为有@Api注解的Controller生成API文档
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
d.为有@ApiOperation注解的方法生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
三、常见注解简介
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象实体来作为入参
@ApiProperty:用对象接实体收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams: 多个请求参数
四、演示(为方便我使用了上面第一种配置)
1、使用原路径访问
2、原路径调试
3、doc模式访问
4、doc模式调试
来源:https://www.cnblogs.com/Tom-shushu/p/14140925.html
标签:SpringBoot,集成,Swagger2
![](/images/zang.png)
![](/images/jiucuo.png)
猜你喜欢
spring validation多层对象校验教程
2023-11-27 15:17:49
SpringBoot实现过滤器和拦截器的方法
2022-10-21 23:29:34
java 学习笔记(入门篇)_多选择结构switch语句
2023-02-04 11:35:59
浅析java中的取整(/)和求余(%)
2023-04-30 23:46:23
Flutter 分页功能表格控件详细解析
2023-09-22 20:02:45
![](https://img.aspxhome.com/file/2023/2/104692_0s.gif)
详解Java字节码编程之非常好用的javassist
2021-08-27 04:54:30
![](https://img.aspxhome.com/file/2023/0/78850_0s.png)
android之BroadcastReceiver应用详解
2021-08-31 16:05:21
![](https://img.aspxhome.com/file/2023/5/139255_0s.png)
C++智能指针实例详解
2021-12-18 00:38:59
Android自定义View图片按Path运动和旋转
2022-09-15 22:53:11
![](https://img.aspxhome.com/file/2023/9/137889_0s.gif)
Spring Boot利用Docker快速部署项目的完整步骤
2022-03-08 18:52:55
![](https://img.aspxhome.com/file/2023/9/84759_0s.png)
Android中AsyncTask与handler用法实例分析
2023-12-04 00:01:52
![](https://img.aspxhome.com/file/2023/8/88128_0s.png)
从零实现一个简单的Spring Bean容器的代码案例
2022-07-24 11:42:16
synchronized背后的monitor锁实现详解
2023-07-31 08:14:10
解析Android中string-array数据源的简单使用
2022-12-19 10:06:53
C#实现装箱与拆箱操作简单实例
2023-09-10 15:37:28
读取spring配置文件的方法(spring读取资源文件)
2022-10-08 11:24:21
Java实现简单文件过滤器功能
2021-09-13 23:27:58
![](https://img.aspxhome.com/file/2023/1/62111_0s.png)
android ItemTouchHelper实现可拖拽和侧滑的列表的示例代码
2023-08-14 14:51:51
![](https://img.aspxhome.com/file/2023/8/100588_0s.gif)
简单实现Android闹钟功能
2022-05-23 16:17:53
![](https://img.aspxhome.com/file/2023/6/108256_0s.jpg)
解决SpringBoot web项目启动后立即关闭的问题
2023-07-26 02:33:37
![](https://img.aspxhome.com/file/2023/9/64909_0s.png)