仅需一个依赖给Swagger换上新皮肤,既简单又炫酷!
  

marco 533

{{ttag.title}}
Swagger作为一款非常流行的API文档生成工具,相信很多小伙伴都在用。Swagger最为方便的地方在于,你的项目只要集成了它,一启动就能生成最新版文档,而且可以在线调试。不过Swagger的接口调试功能确实有很多缺点,比如对JSON支持不太友好。今天我们使用Knife4j来增强下它,使用的是SpringDoc提供的Swagger实现库,希望对大家有所帮助!
聊聊Swagger的Java库
首先我们来聊聊Java中两种比较流行的两种Swagger实现库,对比下哪个更好用。
SpringFox
SpringFox是老牌的Swagger实现库,Github上标星5.6K+,相信很多小伙伴项目中都集成的是这个库。不过该实现库在两年前发了3.0.0版本后就再也没发版本了。而且如果你在SpringBoot 2.6.x版本以上使用的话,会发现许多问题需要自行解决,具体可以参考升级 SpringBoot 2.6.x 版本后,Swagger 没法用了!
SpringDoc
SpringDoc是最近才流行起来的Swagger实现库,Github上标星2K+,版本更新还是很快的,维护更新有保障。之前写过一篇SpringDoc使用教程 大家可以参考下。
SpringDoc的功能还是挺强大的,不仅支持Spring WebMvc项目,还可以支持Spring WebFlux项目。
该选哪个
如果你的项目中已经集成了SpringFox并大量使用了,还是依然使用SpringFox吧,毕竟迁移也是需要成本的。如果你的项目是新项目目前正在技术选型阶段可以考虑使用SpringDoc,毕竟更新维护更有保障。
SpringDoc结合Knife4j使用
Knife4j是一款Swagger UI增强库,之前一直以为它只支持SpringFox,最近发现它也支持了SpringDoc。Knife4j可以无缝支持SpringDoc,仅需添加一个依赖即可,无需修改任何用法,非常方便!
  • 这里我们还是使用SpringDoc使用教程 中的mall-tiny-springdocDemo,首先在pom.xml中添加Knife4j相关依赖;

  • 然后将项目启动起来,访问下Knife4j的默认接口文档地址:http://localhost:8088/doc.html

  • 我们找一个需要提交JSON格式请求参数的接口调试下,发现对于JSON格式参数,Knife4j提供了格式校验功能;

  • 再找个返回数据比较长的接口调试下,Knife4j提供了数据折叠功能,这两个功能确实是我们比较需要的。

Knife4j微服务解决方案更新
之前出了套微服务聚合Swagger的API文档解决方案 ,也使用了Knife4j,最近把它更新支持了最新版Spring Cloud,这里我们再来聊聊这个解决方案。
实现原理
我们理想的解决方案应该是这样的,网关作为API文档的统一入口,网关聚合所有微服务的文档,通过在网关进行切换来实现对其他服务API文档的访问。
相关服务划分:
  • micro-knife4j-gateway:网关服务,作为微服务API文档的访问入口,聚合所有API文档,需要引入文档前端UI包;
  • micro-knife4j-user:用户服务,普通API服务,不需要引入文档前端UI包;
  • micro-knife4j-order:订单服务,普通API服务,不需要引入文档前端UI包。

项目地址
https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j
总结
像Knife4j这种,不改变Swagger原来的使用,能对Swagger进行功能增强的库确实很不错。要是能多几种这种换皮肤的实现库的话,Swagger的使用体验应该会更好!
项目源码地址
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc

打赏鼓励作者,期待更多好文!

打赏
1人已打赏

沧海 发表于 2022-10-18 10:43
  
学习一下,感谢楼主分享
marco 发表于 2022-10-18 13:39
  
感谢楼主分享,学习了。。。。
tianjt 发表于 2022-11-1 09:24
  
每天学习一点新知识,谢谢分享
发表新帖
热门标签
全部标签>
每日一问
技术盲盒
每周精选
干货满满
技术笔记
产品连连看
2024年技术争霸赛
技术咨询
标准化排查
技术晨报
GIF动图学习
2023技术争霸赛专题
安装部署配置
新版本体验
功能体验
自助服务平台操作指引
文档捉虫活动
通用技术
秒懂零信任
信服课堂视频
答题自测
每日一记
玩转零信任
技术圆桌
在线直播
问题分析处理
SDP百科
畅聊IT
专家问答
MVP
网络基础知识
升级
安全攻防
上网策略
测试报告
日志审计
流量管理
运维工具
云计算知识
用户认证
原创分享
解决方案
sangfor周刊
VPN 对接
项目案例
SANGFOR资讯
专家分享
技术顾问
信服故事
功能咨询
终端接入
授权
设备维护
资源访问
地址转换
虚拟机
存储
迁移
加速技术
排障笔记本
产品预警公告
信服圈儿
S豆商城资讯
技术争霸赛
「智能机器人」
追光者计划
深信服技术支持平台
社区帮助指南
答题榜单公布
纪元平台
卧龙计划
华北区拉练
天逸直播
以战代练
山东区技术晨报
齐鲁TV
华北区交付直播

本版版主

12
185
6

发帖

粉丝

关注

本版达人

LoveTec...

本周分享达人

新手24116...

本周提问达人