最新要闻
- 澳大利亚一飞机掉入印度洋:全员坠海 未有伤亡
- 世界速递!比亚迪大疆达成合作!全新海狮将用上高级辅助驾驶技术:纯视觉走天下
- 每日消息!希捷推出星球大战版SSD:三款RGB光剑任选
- 资讯推荐:一图看懂!小米/红米多款热门机型官方降价:小米12S/13全系有活动
- 环球新动态:用两年就卡?3分钟学会选电视硬件
- 当前播报:申城交警多措并举加强高速公路和城市快速路事故预防工作
- 每日视讯:最新确认:小米13 Ultra用上了USB 3.X接口
- 《流浪地球2》4月14日网络首播!导演郭帆:修改了一百多个视效镜头
- 差评高达86%!艺画开天官博恢复《三体》动画相关微博
- 【世界聚看点】等等党狂喜!比亚迪海豹有优惠了:本月订车至享高3.1万元减免
- 全球热门:荣耀Magic5 Pro“首碎”!SUV压过屏幕依旧完好
- 每日热闻!微信界面黑色怎么设置成白色_微信变成黑色怎么调过来
- 最资讯丨马来西亚原装进口:猫山王榴莲雪糕4元/支狂促
- 索尼痛斥英国CMA:偏袒微软过于荒谬
- 当前头条:合资A级轿车更难了!2023款比亚迪秦PLUS EV冠军版上市:12.98万起
- 苹果中国杀疯!iPhone14售价跌破5000元 买它还是华为P60?
手机
iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?
警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案
- iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?
- 警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案
- 男子被关545天申国赔:获赔18万多 驳回精神抚慰金
- 3天内26名本土感染者,辽宁确诊人数已超安徽
- 广西柳州一男子因纠纷杀害三人后自首
- 洱海坠机4名机组人员被批准为烈士 数千干部群众悼念
家电
Springfox与SpringDoc——swagger如何选择(SpringDoc入门)
本文分享自天翼云开发者社区@《Springfox与SpringDoc——swagger如何选择(SpringDoc入门)》,作者: 才开始学技术的小白
0.引言
之前写过一篇关于swagger(实际上是springfox)的使用指南(https://www.ctyun.cn/developer/article/371704742199365),涵盖了本人在开发与学习的时候碰到的各种大坑。但由于springfox已经不更新了,很多项目都在往springdoc迁移
(资料图)
笔者也是花了一些时间试了一下这个号称“把springfox按在地下摩擦”的springdoc究竟好不好使,本文就来简单介绍下springdoc的使用以及优劣势
1.引入maven依赖
这里有个大坑一定要注意!!!
如果你跟我一样,现在使用的是springfox,但是想往springdoc迁移,结果试了一下发现还是springfox好用/懒得改那么多注解,还是想换回springfox,一定要把springdoc的maven依赖删掉!!!不然springboot会默认你用的是springdoc,导致swagger界面出不来
2.springdoc配置类
实际上springdoc的配置非常简单,使用的是OpenAPI类与GroupedOpenApi来配置
/**
* SpringDoc API文档相关配置
* Created by macro on 2023/02/02.
*/@Configurationpublic class SpringDocConfig {
@Bean
public OpenAPI mallTinyOpenAPI() {
return new OpenAPI()
.info(new Info().title("CTYUN API")
.description("SpringDoc API 演示")
.version("v1.0.0")
.license(new License().name("Apache 2.0").url("https://github.com/")))
.externalDocs(new ExternalDocumentation()
.description("SpringBoot项目")
.url("http://www.ctyun.com"));
}
@Bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("admin")
.pathsToMatch("/**")
.build();
}
//可以创建不同的GroupedOpenApi来判断不同的controller
@Bean
public GroupedOpenApi userApi() {
return GroupedOpenApi.builder()
.group("user")
.pathsToMatch("/user/**")
.build();
}}
3.启动
默认配置之后直接进入:http://localhost:8080/swagger-ui/index.html 即可
注意这里与springfox略有不同(http://localhost:8080/swagger-ui.html)
4.与SpringFox的注解对照
5.SpringDoc基本注解用法
这里转载一个写的非常全面的示例接口,原文可以去看:https://blog.csdn.net/zhenghongcs/article/details/123812583
/**
* 品牌管理Controller
* Created by macro on 2019/4/19.
*/@Tag(name = "PmsBrandController", description = "商品品牌管理")@Controller@RequestMapping("/brand")public class PmsBrandController {
@Autowired
private PmsBrandService brandService;
private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
@Operation(summary = "获取所有品牌列表",description = "需要登录后访问")
@RequestMapping(value = "listAll", method = RequestMethod.GET)
@ResponseBody
public CommonResult> getBrandList() {
return CommonResult.success(brandService.listAllBrand());
}
@Operation(summary = "添加品牌")
@RequestMapping(value = "/create", method = RequestMethod.POST)
@ResponseBody
@PreAuthorize("hasRole("ADMIN")")
public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
CommonResult commonResult;
int count = brandService.createBrand(pmsBrand);
if (count == 1) {
commonResult = CommonResult.success(pmsBrand);
LOGGER.debug("createBrand success:{}", pmsBrand);
} else {
commonResult = CommonResult.failed("操作失败");
LOGGER.debug("createBrand failed:{}", pmsBrand);
}
return commonResult;
}
@Operation(summary = "更新指定id品牌信息")
@RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
@ResponseBody
@PreAuthorize("hasRole("ADMIN")")
public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {
CommonResult commonResult;
int count = brandService.updateBrand(id, pmsBrandDto);
if (count == 1) {
commonResult = CommonResult.success(pmsBrandDto);
LOGGER.debug("updateBrand success:{}", pmsBrandDto);
} else {
commonResult = CommonResult.failed("操作失败");
LOGGER.debug("updateBrand failed:{}", pmsBrandDto);
}
return commonResult;
}
@Operation(summary = "删除指定id的品牌")
@RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
@ResponseBody
@PreAuthorize("hasRole("ADMIN")")
public CommonResult deleteBrand(@PathVariable("id") Long id) {
int count = brandService.deleteBrand(id);
if (count == 1) {
LOGGER.debug("deleteBrand success :id={}", id);
return CommonResult.success(null);
} else {
LOGGER.debug("deleteBrand failed :id={}", id);
return CommonResult.failed("操作失败");
}
}
@Operation(summary = "分页查询品牌列表")
@RequestMapping(value = "/list", method = RequestMethod.GET)
@ResponseBody
@PreAuthorize("hasRole("ADMIN")")
public CommonResult
@Parameter(description = "页码") Integer pageNum,
@RequestParam(value = "pageSize", defaultValue = "3")
@Parameter(description = "每页数量") Integer pageSize) {
List
return CommonResult.success(CommonPage.restPage(brandList));
}
@Operation(summary = "获取指定id的品牌详情")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ResponseBody
@PreAuthorize("hasRole("ADMIN")")
public CommonResult
return CommonResult.success(brandService.getBrand(id));
}}
6.与SpringSecurity的结合
如果项目中使用了SpringSecurity,需要做两个配置来让springdoc正常使用:
1.在SpringSecurity配置类中放行白名单:"/v3/api-docs/**", "/swagger-ui/**"
2.在SpringDoc配置中增加对应内容,如下:
@Configurationpublic class SpringDocConfig {
private static final String SECURITY_SCHEME_NAME = "BearerAuth";
@Bean
public OpenAPI managerOpenAPI() {
return new OpenAPI()
.info(new Info().title("Galaxy-Cluster-Manager后端接口文档")
.description("提供给前端界面(portal)的接口文档")
.version("v1.0.0")
.license(new License().name("galaxy 1.2.0").url("https://gitlab.ctyun.cn/hpc/galaxy-parent/-/tree/v1.2.0")))
.externalDocs(new ExternalDocumentation()
.description("弹性高性能计算(CTHPC)")
.url("http://www.ctyun.cn"))
//以下是针对SpringSecurity的设置,同时还有设置白名单
.addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
.components(new Components()
.addSecuritySchemes(SECURITY_SCHEME_NAME,
new SecurityScheme()
.name(SECURITY_SCHEME_NAME)
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")));
}
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("portal")
.pathsToMatch("/api/**")
.build();
}
}
7.SpringDoc使用对象作为Query参数的问题
实际上springfox也会有这个问题,使用对象作为query传参的时候,页面通常是这样的:
就没有办法逐个描述参数,也不能逐个调试(只能用json调试),非常的麻烦;springdoc有一个解决这个问题非常方便的注解:@ParameterObject
比如某一个控制器的入参是User user,我们只需要在这前面加上注解变为:@ParameterObject User user 即可,结果如下;
这里也有一个大坑:参数的类型可能会不正确,比如这里我们的id参数实际上是int,但显示出来是string,这个时候就需要我们在User类的属性中加上对应的注解,比如:
@Parameter(description = "id传参",example = "6")
再重启UI就会发现参数类型正确了
8.SpringDoc配置扫包范围
有的时候仅仅使用@Hidden并不能满足我们的需要,因为可能需要配置不同group的controller类,这个时候就需要在配置类中取设置扫包范围代码如下:
9.SpringDoc的优劣势
优势:SpringDoc有着非常好看的UI,以及比Springfox更加完善的参数注解体系,看起来非常舒服,并且还在不断更新与维护中
劣势:一些冷门功能还不完善,比如:
a.有十个接口,他们的url是一样的但是可以通过query参数来分别(如:@PostMapping(params = "action=QueryUsers"))这个时候springdoc只能通过扫包范围配置,来写多个GroupOpenApi来解决,非常的麻烦;springfox可以在docket创建的时候使用:docket.enableUrlTemplating(true); 这个方法即可解决
b.springdoc的网络配置可能会与springfox冲突,如果迁移,需要逐个尝试网络配置是否合适(主要是GsonHttpMessageConverter的配置)
c.兼容性问题仍需要观望,相对于springfox,springdoc的兼容性并没有那么好,在许多时候可能会出现序列化的乱码问题
总结:如果当前项目/工程已经集成了完备的springfox,建议不要轻易尝试迁移到springdoc,尤其是接口类型比较复杂、springfox配置docket比较多的项目;但如果是从头开始的项目,由于接口相对比较简单,可以采用springdoc,毕竟可以获得更加清晰明了的显示界面与参数解释。
关键词:
-
当前要闻:易基因:群体分析揭示了DNA甲基化在番茄驯化和代谢多样性中的作用|组学研究
大家好,这里是专注表观组学十余年,领跑多组学科研服务的易基因。2023年3月23日,海南大学三亚南繁研究...
来源: -
Springfox与SpringDoc——swagger如何选择(SpringDoc入门)
本文分享自天翼云开发者社区@《Springfox与SpringDoc——swagger如何选择(SpringDoc入门)》,作者:才...
来源: 当前要闻:易基因:群体分析揭示了DNA甲基化在番茄驯化和代谢多样性中的作用|组学研究
记录-VueJs中如何使用Teleport组件
Springfox与SpringDoc——swagger如何选择(SpringDoc入门)
澳大利亚一飞机掉入印度洋:全员坠海 未有伤亡
世界速递!比亚迪大疆达成合作!全新海狮将用上高级辅助驾驶技术:纯视觉走天下
每日消息!希捷推出星球大战版SSD:三款RGB光剑任选
资讯推荐:一图看懂!小米/红米多款热门机型官方降价:小米12S/13全系有活动
环球新动态:用两年就卡?3分钟学会选电视硬件
当前播报:申城交警多措并举加强高速公路和城市快速路事故预防工作
世界头条:用 Go 剑指 Offer 17. 打印从1到最大的n位数
【天天时快讯】获取Python函数信息的方法
世界信息:GPT对SaaS领域有什么影响?
全球新资讯:什么是 Java 字节码?采用字节码的好处是什么?
【天天聚看点】ubuntu离线安装tcpdump
因债券承销尽调不充分等问题 民生证券被上交所出具书面警示
每日视讯:最新确认:小米13 Ultra用上了USB 3.X接口
《流浪地球2》4月14日网络首播!导演郭帆:修改了一百多个视效镜头
差评高达86%!艺画开天官博恢复《三体》动画相关微博
【世界聚看点】等等党狂喜!比亚迪海豹有优惠了:本月订车至享高3.1万元减免
全球热门:荣耀Magic5 Pro“首碎”!SUV压过屏幕依旧完好
每日热闻!微信界面黑色怎么设置成白色_微信变成黑色怎么调过来
【独家】使用Drone+gitea配置自己的CICD流程
全球热消息:收评:两市震荡走强创指涨0.84% 医药、人工智能概念涨幅居前
最资讯丨马来西亚原装进口:猫山王榴莲雪糕4元/支狂促
索尼痛斥英国CMA:偏袒微软过于荒谬
当前头条:合资A级轿车更难了!2023款比亚迪秦PLUS EV冠军版上市:12.98万起
苹果中国杀疯!iPhone14售价跌破5000元 买它还是华为P60?
环球要闻:网红密子君带货无骨鸡爪!粉丝提醒她有蟑螂 本人道歉
保罗:比赛起起伏伏很奇怪 从未跟KD这种能吸引包夹的球员共事过
焦点热门:全文索引:Apache Lucene(一)
天天热讯:Java 自增自减运算符和移位运算符介绍
世界观速讯丨NTP时间同步服务器(频率同步)包含帧同步、载波同步、位同步
sms-activate短信验证码问题
世界新资讯:153. 寻找旋转排序数组中的最小值
【财经分析】新规创新保险服务模式 完善多层次长期护理保障制度
国风开放世界新作:网易新游《暂时叫它:天字七六》公布
世界今热点:全新MacBook要用OLED屏!如果不烧屏还是挺香的
或8万起售 比亚迪海鸥四颜色曝光:绿、黑、白、粉你选谁
这可能是最好看的RX 7900 XTX:华擎发布太极白色版
科大讯飞刘聪:5月6日将发布“1+N认知智能大模型”
泫雅和张贤胜的组合叫什么?泫雅和张贤胜在一起过吗?
蛇沼鬼城后面一部是什么?蛇沼鬼城录像带里的吴邪是谁?
张一山为什么剃光头?张一山出演的电视剧有哪些?
南派三叔为什么要封笔?南派三叔的全部作品顺序
被嫌弃的松子的一生讲了什么? 松子一生坎坷结局是怎么死的?
【新视野】山西省印发钢铁行业转型升级2023年行动计划
全球播报:[Web Server]Tomcat调优之监控连接池/线程池
焦点快播:(笔记)电源缓启动工作原理
世界速看:详解 Flink Catalog 在 ChunJun 中的实践之路
【环球速看料】Python selenium过图片滑块验证
拼多多百亿补贴“厂家直销”受阻:京东自营再现“排他性”竞争
细思极恐!韩国分析日本农产品超20%检出放射性物质铯
环球热讯:南财基金通·混合型基金收益排行榜(4月6日)
【天天热闻】Java中子类重写父类方法的思想本质!
头条焦点:CRLF和LF区别
焦点日报:买车更方便!新车上牌免查验试点新增21个城市:看看有你家吗
天天资讯:工资6000面试6轮当事人发声:没被录用 可能介意我年龄大
当前观察:出游正值好春光!“五一”旅游需求爆发
为何全球这么多人首选iPhone:苹果保值率第一 安卓机惨
环球资讯:气象台:未来十天冷空气影响频繁 9日起沙尘天气将卷土重来
天天动态:分库分表之ShardingSphere
要闻:新农保和社保可以同时交不_新农保和社保可以同时交
真不是人扮的?黑猩猩吃完饭主动到水池里洗盘子游客看呆
每日速看!离地球最近的黑洞被发现!科学家:还有许多黑洞待发现
焦点日报:比亚迪百万级纯电超跑!仰望U9确定参加上海车展:加速2秒级
中规中矩!杜兰特半场10中4得11分5板2助 共出现3次失误
天天资讯:开源即时通讯IM框架MobileIMSDK的微信小程序端开发快速入门
ONLYOFFICE 安装对接指南
今日快看!极氪员工泄露文件 疑与投诉车主沟通删帖内幕曝光!客服回应
环球关注:3折奔驰GLS很香?博主理性分析29万买北汽BJ90:不如现代帕里斯帝
热文:巨头联手!抖音宣布与腾讯视频合作:可以合法二创了
焦点报道:岚图汽车公开挑战保时捷、奥迪、蔚来和极氪 网友:你“图”什么
每日播报!全国56门店通用:瑞慈全身体检套餐279元大促(800元券)
全球热头条丨瓶装75度的酒精怎么使用?
天天最新:分库分表以后如何对非Sharding键进行查询?
全球最新:Flutter 的优缺点及前景
世界看热讯:人社部要求各地充分挖掘就业渠道 兜牢青年就业底线
焦点消息!搞事情?日本、韩国科学家联手发现未知铀同位素 半衰期超短
世界信息:锐龙7 7800X3D闪电登上热销第一!锐龙9 3D立刻大降价
天天新消息丨比亚迪云辇系统重要信息提前透露:为智能车身控制
iPhone 8以上都能用!中国广电5G宣布:已全面支持iPhone
环球消息!一人之下!特斯拉任命朱晓彤为汽车业务高级副总裁
世界最新:研究:ChatGPT影响用户道德判断
低至2.5折!Epic春季特卖来了:超1800款游戏便宜卖
读SQL进阶教程笔记09_HAVING上
【全球聚看点】【读财报】3月上市公司再融资动态:定增实际募资693亿元 邮储银行、中核钛白募资额居前
RTX 4070官方走光:NVIDIA声称4799元很便宜!
全球看点:为了逃离俄罗斯:美国思科狠心销毁1.6亿元设备
当前速看:沙特俄罗斯减产 油价看高至100美元:美国难受 但日韩最遭殃
全球快报:昊华科技:4月6日融资买入87.08万元,融资融券余额9058.06万元
【新视野】2、XmlBeanFactory 的类图介绍.md
全球观点:执行orachk检查数据库环境
今日快讯:姆总很生气!头号射手和大巴黎翻脸,想要姆巴佩原谅必须得加钱
【独家焦点】王者面前蹦迪 本田思域高速见缝插针式变道被撞惨
今日观点!人死后葬礼要花多少钱?为什么现在的死亡成本这么高?
全球微速讯:百元级主板也能上游戏神U 微星A620升级支持锐龙7 7800X3D
麦当劳是怎么在年轻人心中封神的?
卫生间、厨房还是阳台? 新房装修洗衣机真不能随便放
春泉产业信托(01426.HK)4月6日回购6万个基金单位
【聚看点】数据库系统原理之数据管理技术的发展