Swagger 问题修复说明

问题描述

访问Swagger文档时出现以下错误：

Illegal DefaultValue null for parameter type integer java.lang.NumberFormatException: For input string: ""

问题原因

Swagger在解析@RequestParam注解时，对于Long类型参数的defaultValue处理有兼容性问题，特别是在以下情况：

1. Long类型参数使用defaultValue

   @RequestParam(defaultValue = "1") Long current

2. Swagger版本兼容性

   • SpringFox 3.0.0 对Long类型的默认值解析存在bug
   • 在序列化为JSON时会尝试将空字符串转换为Long类型

解决方案

方案1：修改参数类型（已采用）

将Long类型参数改为Integer类型：

// 修改前 @RequestParam(defaultValue = "1") Long current // 修改后 @RequestParam(defaultValue = "1") Integer current

优点：

• 简单直接，兼容性好
• Integer类型足够满足分页参数需求
• 不需要额外配置

修改内容：

@GetMapping("/page") public R<IPage<ChatRecord>> pageList( @ApiParam(value = "当前页", example = "1") @RequestParam(defaultValue = "1") Integer current, @ApiParam(value = "每页条数", example = "10") @RequestParam(defaultValue = "10") Integer size, // ... 其他参数 ) { // 转换为Long类型传给MyBatis-Plus Page<ChatRecord> page = new Page<>(current.longValue(), size.longValue()); // ... }

方案2：创建Swagger配置类（备用）

创建SwaggerConfig来处理类型替换：

@Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.hzys.controller")) .paths(PathSelectors.any()) .build() // 解决Long类型参数在Swagger中的显示问题 .directModelSubstitute(Long.class, String.class); } }

方案3：使用@ApiParam的example属性

为参数添加明确的示例值：

@ApiParam(value = "当前页", example = "1") @RequestParam(defaultValue = "1") Integer current

最佳实践

1. 分页参数推荐使用Integer

// ✅ 推荐：使用Integer @RequestParam(defaultValue = "1") Integer current @RequestParam(defaultValue = "10") Integer size // ❌ 不推荐：使用Long（可能有Swagger兼容问题） @RequestParam(defaultValue = "1") Long current @RequestParam(defaultValue = "10") Long size

2. 为所有参数添加示例值

@ApiParam(value = "当前页", example = "1") @RequestParam(defaultValue = "1") Integer current @ApiParam(value = "每页条数", example = "10") @RequestParam(defaultValue = "10") Integer size @ApiParam(value = "用户ID", example = "user001") @RequestParam(required = false) String userId

3. 统一的分页参数处理

创建通用的分页参数对象：

@Data @ApiModel("分页参数") public class PageParam { @ApiModelProperty(value = "当前页", example = "1") private Integer current = 1; @ApiModelProperty(value = "每页条数", example = "10") private Integer size = 10; public Page<T> toPage() { return new Page<>(current.longValue(), size.longValue()); } } // 在Controller中使用 @GetMapping("/page") public R<IPage<ChatRecord>> pageList(PageParam pageParam, @RequestParam(required = false) String userId) { Page<ChatRecord> page = pageParam.toPage(); // ... }

验证修复

1. 重启应用

重启Spring Boot应用。

2. 访问Swagger文档

访问：http://localhost:8091/swagger-ui/index.html

3. 检查分页接口

找到"聊天记录管理"下的"分页查询聊天记录"接口，确认：

• 参数显示正常
• 没有错误信息
• 可以正常测试

4. 测试接口

# 测试分页接口 curl "http://localhost:8091/api/chat/record/page?current=1&size=10"

其他可能的Swagger问题

1. 枚举类型显示问题

如果枚举在Swagger中显示有问题，可以添加：

@ApiModelProperty(value = "消息类型", example = "1", allowableValues = "1,2,3") private Integer msgType;

2. 日期时间格式问题

对于日期时间字段：

@ApiModelProperty(value = "反馈时间", example = "2026-01-16 10:00:00") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss") private String feedbackTime;

3. 文件上传参数问题

对于文件上传：

@ApiParam(value = "上传文件", required = true) @RequestParam("file") MultipartFile file

相关配置文件

已创建的文件

1. SwaggerConfig.java- Swagger配置类

   • 位置：src/main/java/com/hzys/base/config/SwaggerConfig.java
   • 作用：统一配置Swagger，处理类型兼容问题

2. 修改的文件

   • ChatRecordController.java- 修改分页参数类型

Swagger依赖

确认pom.xml中有正确的Swagger依赖：

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>

总结

修复内容

✅ 将Long类型分页参数改为Integer类型
✅ 添加了@ApiParam的example属性
✅ 创建了SwaggerConfig配置类
✅ 提供了最佳实践建议

预防措施

1. 避免在@RequestParam中使用Long类型的defaultValue
2. 为所有API参数添加example示例值
3. 统一使用Integer类型处理分页参数
4. 定期测试Swagger文档的可用性

如果问题仍然存在

1. 检查Swagger版本兼容性
2. 查看控制台是否有其他错误信息
3. 尝试降级SpringFox版本到2.x
4. 考虑使用SpringDoc替代SpringFox

参考资料

• SpringFox官方文档
• Swagger注解使用指南
• SpringBoot集成Swagger最佳实践