kl个人博客 首页>>Spring>>Swagger异常定位纪实,是用的不对,还是Swagger本身设计问题

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

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的页面时会抛出,每次刷新页面,获取一次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,在触发异常的地方打上断点。触发异常,进入断点,获取到了关键信息

一个被描述为app id的字段,用这个信息全局搜索,得到如下的结果:

有三个相关的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判断了下,所以不会触发异常了

为啥不直接升级3.x?

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