记一次knife4j文档请求异常 SyntaxError: Unexpected token ‘＜‘, ... is not valid JSON

news2024/12/27 10:36:43

knife4j页面报错问题定位

前几天开发新接口，开发完成后想使用knife4j测试一下接口功能，突然发现访问页面报错提示：knife4j文档请求异常，但之前运行还是正常的，想想会不会与升级依赖有关系，启动其他微服务发现文档接口访问正常，排除因依赖版本升级导致在线API文档无法使用情况，还是和本服务新增接口有关系。

定位问题

首先f12打开调试台，重新刷新页面，看到console有报错提示
在这里插入图片描述
查看报错提示信息好像是某个返回结构不是json形式，还是有点模糊，于是搜索相关错误信息，并未发现类似问题

查询开源组件issues

于是进入knife4j的开源仓库，找到了一个类似问题，发现有其他同学提过类似问题
开源组件issue地址
https://gitee.com/xiaoym/knife4j/issues/I92QJB
在这里插入图片描述

大佬给出问题原因可能是：接口响应的内容，不是json，找找你框架自己的原因，于是重新回到自己的接口上面

定位具体有问题的接口

由于项目接口非常多，高达几百个，无法精准定位到时具体哪个接口导致加载页面报错，虽然该问题不影响具体功能，但是遇到问题不解决有种如鲠在喉的感觉。没办法采用笨方法，查看最近新增的Controller，采用折半形式终于找到了产生问题的Controller类，然后采用类似方法继续找到了产生问题的接口

@ApiOperation(value = "业务系统大屏", notes = "业务系统大屏")
@PostMapping(value = "/business/detail", produces = "application/json;charset=UTF-8")
 public BusinessDetailResults businessLeakDetail(@Valid @RequestBody BusinessDetailCondition condition) throws Exception {
     return businessDetailService.businessDetail(condition);
 }

定位根因

对比接口和其他接口定义差不多没有发现啥明显问题，然后进入返回结果BusinessDetailResults类发现类上没有添加@ApiModel怀疑是因为这个问题导致的，于是添加上注解，然后重启服务发现问题仍然没有解决，于是把目光聚集到BusinessDetailCondition类上，进入该类好像也没有啥明显问题

@ApiModel(value = "业务系统查询条件")
public class BusinessDetailCondition extends PageCondition {
    @ApiModelProperty(value = "区域ID", example = "[1,2,3]")
    private List<Integer> areaIds;

    @ApiModelProperty(value = "租户ID", example = "[1,2,3]")
    private List<Integer> tenantIds;

    @ApiModelProperty(value = "url集合", example = "['https://baidu.com]'")
    @NotEmpty
    private List<String> domainList;
    ......
}

当时怀疑难道是因为中括号导致无法解析，于是将三个中括号去除，然后访问在线文档页面发现页面可以正常访问了，是否可以下结论是中括号引起的呢？查看接口的请求实例
在这里插入图片描述

发现本来应该是数组的字段全变成了string类型，想想不应该因为中括号的存在导致api在线文档页面无法访问，于是继续测试发现只有domainList的example在添加[]的情况下会导致页面报错，为什么其他两个不会报错呢，继续查看上面的页面报错信息恍然明白，其他两个字段example中也使用了[]，其实是因为字段类型都是Integer类型无需使用双引号包裹，重新将domainList字段描述进行修改

@ApiModelProperty(value = "url集合", example = "[\"https://baidu.com\"]")

重新启动微服务，访问在线文档页面发现恢复正常。最后发现是其他同事在添加描述时候不小心没有对string类型添加双引号包裹导致页面在加载时候解析这个json报错
在这里插入图片描述

总结：

其实上面描述的问题只是一个很小很小的疏忽导致在线接口文档无法访问，还好没有影响到生产环境其他功能。本篇文章也只是记录一下生产过程中的一个小问题的定位和处理过程，但是每个人的情况都不尽相同，希望对您在遇到相同问题时候有一点帮助。回头再看一下报错信息，你会发现其实已经给出了具体提示，只是一开始我们没有理解而已。以此记录一下，希望自己下次可以关注细节
在这里插入图片描述