Swagger异常定位纪实,是用的不对,还是Swagger本身设计问题-阿里云开发者社区

开发者社区> kl小陈> 正文

Swagger异常定位纪实,是用的不对,还是Swagger本身设计问题

简介: swagger ui是一个采用注解驱动的接口文档工具,目前已支持标准的open api v3规范协议,所以不仅可以在java项目里使用,每个语言都有相应的open api实现。项目集成swagger后,可以生成导出open api v3格式化的元数据集,有了这个接口元数据,你可以在任何支持v3协议的ui上展示你的api信息。在前后端分离的项目中,swagger ui的出现,大大提高了前后端联调的效率。swagger ui在解析注解标注的元数据信息时,特别场景下会抛异常,而且抛的异常没有直观的有价值的异常信息,所以深入的debug了一番,虽然最后问题解决很简单,但是过程非常曲折。故将bug定位过
+关注继续查看

前言

swagger ui是一个采用注解驱动的接口文档工具,目前已支持标准的open api v3规范协议,所以不仅可以在java项目里使用,每个语言都有相应的open api实现。项目集成swagger后,可以生成导出open api v3格式化的元数据集,有了这个接口元数据,你可以在任何支持v3协议的ui上展示你的api信息。在前后端分离的项目中,swagger ui的出现,大大提高了前后端联调的效率。swagger ui在解析注解标注的元数据信息时,特别场景下会抛异常,而且抛的异常没有直观的有价值的异常信息,所以深入的debug了一番,虽然最后问题解决很简单,但是过程非常曲折。故将bug定位过程记录在此。

异常信息

image2020-12-9_14-52-22.png
这个异常只会在加载swagger-ui的页面时会抛出,每次刷新页面,获取一次api接口就会触发一次异常。

异常分析

@JsonProperty("x-example")
public Object getExample() {
    if (example == null) {
        return null;
 }
    try {
        if (BaseIntegerProperty.TYPE.equals(type)) {
            return Long.valueOf(example);
 } else if (DecimalProperty.TYPE.equals(type)) {
            return Double.valueOf(example);
 } else if (BooleanProperty.TYPE.equals(type)) {
            if ("true".equalsIgnoreCase(example) || "false".equalsIgnoreCase(defaultValue)) {
                return Boolean.valueOf(example);
 }
        }
    } catch (NumberFormatException e) {
        LOGGER.warn(String.format("Illegal DefaultValue %s for parameter type %s", defaultValue, type), e);
 }
    return example;
}

如上是异常相关的代码。从异常信息表象来看,是一个强转导致的问题,代码试图将一个空的字符串转换成数值类型导致异常抛出。并且是getExample时抛出的异常,这里需要了解swagger ui的加载过程和基础架构才能直接定位。swagger中的example是为了在生成的api doc中,给出相关字段的调用示例,并在触发接口调用时,默认自动填充example的值。这里显然是哪个地方的example设置不合理导致的异常。那么,接下来要做的就是找到这个空字符串的原始代码。

debug找到真实原因

借助IDEA的debug功能,点击异常后面的create breakpoint,在触发异常的地方打上断点。触发异常,进入断点,获取到了关键信息
2AA6B340-A9D5-4D36-9DD5-D622875B9E32.png

一个被描述为app id的字段,用这个信息全局搜索,得到如下的结果:
image2020-12-9_15-22-46.png

有三个相关的Model实体,首先,这三个Model的appId字段都没有设置过example属性,所以,到这一步,可以先下一个小的结论,不是我们设置的example导致的问题,默认在不设置的情况下,example的默认值就是空字符串。然后肯定只有其中一个有问题,因为异常只会触发一次。在不知道结果情况下,依次对这三个Model的appId字段加上正确的example描述,经测试,只有GetAppBannerRequestDTO加上时,异常才消失,罪魁祸首就是它了。但是,为什么呢?其他两个Model为啥就没有问题呢?在博主交叉测验后,发现了最终的原因。

结论及注意事项

当Model作用于请求的接收参数时,并且请求的类型为GET,那么Swagger Ui会自动收集Model所有属性的examole参数,因为这个参数是字符串类型,所以会做一个类型转换动作。当字段类型为数值类型,又有没手动设置example的值,那么Swagger框架拿到的是个空字符串,强转空字符串就抛异常了。而如果请求是POST,就不会触发这段逻辑,所以同为携带数值类型DTO的ImgReplaceRequestDTO没有问题。如果不是接收参数,作为响应参数,也不会触发这段逻辑,故而AppBannerResponseVO也就没有问题了。所以,需要注意的就是当DTO作用于GET请求的接收参数时,切记给所有的数值类型加上正确的example属性

后记

博主认为这里属于一个设计缺陷,而不是我们的使用问题。在获取example的逻辑里,第一段代码就判断了example是否为null。这表明了example有可能为空,但是默认值却设置了一个空字符串。代表不手动将example设置为null,这段判null返回的逻辑就永远跑不到,而且没人会这么做,手动给example设置为null。况且,在触发异常的这种场景下,框架不能强制使用者设置example这种操作。在github仓库追踪这块代码发现,目前Swagger ui已经迈入了3.x版本,全面基于open api v3协议规范设计。所以,这部分代码完全不一样了。而存档的1.5x版本这个问题依旧。

下面是3.x的处理方式,虽然example的默认值还是“”。但是通过NotBlank判断了下,所以不会触发异常了
image2020-12-9_16-34-14.png

为啥不直接升级3.x?

3.x版本既然已经修复了,为啥不直接升级到3.x版本呢?可能有人会有这个疑问。Swagger3.x版本属于一个大跨度的迭代版本,和之前的版本完全不兼容,3.x主要面向了open api v3规范协议设计实现,注解实体等模型都是一一对应的。而在这个版本之前的1.5x系列版本是Swagger自己设计的api模型。所以代码层上面完全不兼容,升级的工作量会非常大。不过,新项目还是推荐使用3.x版本,这个版本的api数据更通用。可以根据api的数据生成各种语言的客户端包。就像proto生成客户端包一样。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
iOS11问题: 定位服务在iOS11系统上不能使用?
iOS11问题: 定位服务在iOS11系统上不能使用? Q:我刚刚用iOS11 SDK重新构建了应用程序,发现定位服务现在根本不起作用。 原因:A:因为苹果现在增加了一项新的隐私保护功能 NSLocationAlwaysAndWhenInUseUsageDeion, 并且原有的 NSLocationAlwaysUsageDeion 被降级为 NSLocationWhenInUseUsageDeion。
973 0
如何设计高效合理的MySQl查询语句?23种常用类型汇总(珍藏版)
MySQL对于很多Linux从业者而言,是一个非常棘手的问题,多数情况都是因为对数据库出现问题的情况和处理思路不清晰。在进行MySQL的优化之前必须要了解的就是MySQL的查询过程,很多的查询优化工作实际上就是遵循一些原则让MySQL的优化器能够按照预想的合理方式运行而已。
1135 0
Arthas 定位 Dubbo 手动注册 Eureka 异常
很久没有写技术分享博客,因为发现一个好的工具确实有点忍不住分享一下,毕竟独乐乐不如众乐乐。这里需要说的主角就是 Artahs。Arthas 使用文档很详细,我这里主要记录一下使用 Arthas 的一点总结。
3363 0
Swagger异常定位纪实,是用的不对,还是Swagger本身设计问题
swagger ui是一个采用注解驱动的接口文档工具,目前已支持标准的open api v3规范协议,所以不仅可以在java项目里使用,每个语言都有相应的open api实现。项目集成swagger后,可以生成导出open api v3格式化的元数据集,有了这个接口元数据,你可以在任何支持v3协议的ui上展示你的api信息。在前后端分离的项目中,swagger ui的出现,大大提高了前后端联调的效率。swagger ui在解析注解标注的元数据信息时,特别场景下会抛异常,而且抛的异常没有直观的有价值的异常信息,所以深入的debug了一番,虽然最后问题解决很简单,但是过程非常曲折。故将bug定位过
572 0
[转贴]40种网站设计常用技巧(Javascript)
回到家了,没有开发环境,这几天只能看网页学习一下。这是csdn上转载的一篇,有些东东还是值得一看的。1. oncontextmenu="window.event.returnValue=false" 将彻底屏蔽鼠标右键no 可用于Table 2.
659 0
我在架构设计和代码开发中的一些常用原则
在日常的开发和设计过程中,大家对技术设计上的一些问题往往会面临很多的选择,不同的人会有不同的选择。本文介绍的就是我在工作中遇到的一些问题而总结和使用到的一些常用原则。
1163 0
Java 编程中关于异常处理的 10 个最佳实践
异常处理是Java 开发中的一个重要部分。它是关乎每个应用的一个非功能性需求,是为了处理任何错误状况,比如资源不可访问,非法输入,空输入等等。
754 0
+关注
kl小陈
互联网从业者,关注分布式,微服务,云原生应用等领域,曾主导过公司单体架构到分布式系统的升级。开源爱好者,目前开源了6个项目,热门项目获码云GVP最具价值项目。长期维护独立博客-kl博客,热衷传播技术分享知识。现任凯京科技架构部负责人。
8
文章
1
问答
来源圈子
更多
阿里云最有价值专家,简称 MVP(Most Valuable Professional),是专注于帮助他人充分了解和使用阿里云技术的意见领袖阿里云 MVP 奖项为我们提供了这样一个机会,向杰出的意见领袖表示感谢,更希望通过 MVP 将开发者的声音反映到我们的技术路线图上。
+ 订阅
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载