SpringBoot开发案例之整合Swagger篇
时间:2022-05-06
本文章向大家介绍SpringBoot开发案例之整合Swagger篇,主要内容包括简介、添加Swagger2依赖、创建Swagger2配置类、添加API注解、访问、基本概念、基础应用、原理机制和需要注意的事项等,并结合实例形式分析了其使用技巧,希望通过本文能帮助到大家理解应用这部分内容。
前段时间整合过的一个支付服务,由于使用了Spring Boot快速开发,但是又懒得写详细的文档介绍,便顺手就把Swagger整合进来了,对支付服务进行分组API展示,如上图。
简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新 。接口的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
在实际开发过程中,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发、Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
- 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳
- 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象
而swagger完美的解决了上面的几个问题,并与Spring boot程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能 来调试每个RESTful API。
添加Swagger2依赖
<!-- swagger2 文档 截止目前 为最新版本 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
创建Swagger2配置类
在Application.java同级包下创建Swagger2的配置类。
@Configuration //让Spring来加载该类配置
@EnableSwagger2 //启用Swagger2
public class Swagger2 {
@Bean
public Docket alipayApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("支付宝API接口文档")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.alipay"))
.paths(PathSelectors.any()).build();
}
@Bean
public Docket weixinpayApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("微信API接口文档")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.weixinpay"))
.paths(PathSelectors.any()).build();
}
@Bean
public Docket unionpayApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("银联API接口文档")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.unionpay"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("支付系统")
.description("微信、支付宝、银联支付服务")
.termsOfServiceUrl("http://blog.52itstyle.com")
.contact(new Contact("科帮网 ", "http://blog.52itstyle.com", "345849402@qq.com"))
.version("1.0").build();
}
}
添加API注解
API说明:
/**
swagger2使用说明:
@Api:用在类上,说明该类的作用
@ApiOperation:用在方法上,说明方法的作用
@ApiIgnore:使用该注解忽略这个API
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
paramType:参数放在哪个地方
header-->请求参数的获取:@RequestHeader
query-->请求参数的获取:@RequestParam
path(用于restful接口)-->请求参数的获取:@PathVariable
body(不常用)
form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
*/
代码实现:
/**
* 银联支付
* 创建者 科帮网
* 创建时间 2017年8月2日
*/
@Api(tags ="银联支付")
@Controller
@RequestMapping(value = "unionpay")
public class UnionPayController {
private static final Logger logger = LoggerFactory.getLogger(AliPayController.class);
@Autowired
private IUnionPayService unionPayService;
@ApiOperation(value="银联支付主页") @RequestMapping(value="index",method=RequestMethod.GET)
public String index() {
return "unionpay/index";
}
@ApiOperation(value="电脑支付")
@RequestMapping(value="pcPay",method=RequestMethod.POST)
@ApiImplicitParam(name = "product", value = "产品信息", required = true, dataType = "Product")
public String pcPay(Product product,ModelMap map) {
logger.info("电脑支付");
product.setPayWay(PayWay.PC.getCode());
String form = unionPayService.unionPay(product);
map.addAttribute("form", form);
return "unionpay/pay";
}
@ApiIgnore//使用该注解忽略这个API
@ApiOperation(value="手机H5支付")
@RequestMapping(value="mobilePay",method=RequestMethod.POST)
public String mobilePay(Product product,ModelMap map) {
logger.info("手机H5支付");
product.setPayWay(PayWay.MOBILE.getCode());
String form = unionPayService.unionPay(product);
map.addAttribute("form", form);
return "unionpay/pay";
}
}
访问
配置完成后,我们重启服务,访问地址 http://localhost:8080/项目名/swagger-ui.html,如:
http://localhost:8080/springboot_pay/swagger-ui.html
完整项目案例可查看 支付服务。
- android EventBus 3.0使用指南
- C++ STL之deque的基本操作
- Android 四种常见的线程池
- Java注解
- C++ STL之排序算法
- Android View架构总结
- 怎样用Python给宝宝取个好名字?
- 字符串处理技巧
- SwipeRefreshLayout下拉刷新组件
- 使用数字进行字符遍历
- 技术分享:杂谈如何绕过WAF(Web应用防火墙)
- 模拟Executor策略的实现如何控制执行顺序?怎么限制最大同时开启线程的个数?为什么要有一个线程来将结束的线程移除出执行区?转移线程的时候要判断线程是否为空遍历线程的容器会抛出ConcurrentM
- ViewPager快速实现引导页
- Linux学习 - 常用和不太常用的实用awk命令
- java教程
- Java快速入门
- Java 开发环境配置
- Java基本语法
- Java 对象和类
- Java 基本数据类型
- Java 变量类型
- Java 修饰符
- Java 运算符
- Java 循环结构
- Java 分支结构
- Java Number类
- Java Character类
- Java String类
- Java StringBuffer和StringBuilder类
- Java 数组
- Java 日期时间
- Java 正则表达式
- Java 方法
- Java 流(Stream)、文件(File)和IO
- Java 异常处理
- Java 继承
- Java 重写(Override)与重载(Overload)
- Java 多态
- Java 抽象类
- Java 封装
- Java 接口
- Java 包(package)
- Java 数据结构
- Java 集合框架
- Java 泛型
- Java 序列化
- Java 网络编程
- Java 发送邮件
- Java 多线程编程
- Java Applet基础
- Java 文档注释
- Git库迁移步骤(从服务器A迁移至服务器B)
- springboot源码解析(四)
- 第2天:网易2018年校园招聘NLP算法工程师笔试试卷分析(二)
- Windows下Scoop安装、配置与使用
- Flutter免费iOS真机调试 AndroidStudio iPhone真机运行教程
- Flutter GridView 网格控件
- Flutter ListView 下拉刷新,上拉加载更多
- Flutter问题:import 'package:english_words/english_words.dart'失败
- 第17天:NLP实战(一)——爬取语料及其简单分析
- 搞懂 Redis 缓存穿透、击穿、雪崩
- win10_opencv4.2_cuda11_vs2019 编译
- (Demo分享)利用JavaScript(JS)做一个可输入分钟的倒计时钟功能
- Flutter ListView 列表控件
- 第18天:NLP实战(二)——用DNN实现手势识别
- 「0821更新」Flutter入门系列教程汇总