前言
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生成客户端包一样。
本文同步分享在 博客“kailing”（other）。
如有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一起分享。
