Spring Boot 3.2.1迁移后@PathVariable参数异常及Swagger显示问题

一、@PathVariable接口返回500错误的解决 #

1. 检查参数合法性与类型转换 #

Spring 6（Spring Boot 3.x基于此框架）对请求参数的类型校验更严格，如果路径中的fiscalYear不是有效整数，会直接抛出类型转换异常导致500：

• 测试时传入合法整数值，比如api/account/2024，避免传入非整数内容
• 若需要兼容非整数输入，可将参数类型改为String后自行转换，或添加全局异常处理器捕获TypeMismatchException，返回友好提示

2. 显式指定@PathVariable参数名称 #

如果项目编译时未保留参数名称（比如未开启-parameters编译参数），Spring可能无法自动绑定参数名。直接给@PathVariable指定参数名即可：

@GetMapping(path = "/{fiscalYear}")
public Response getAccountDetails(@PathVariable("fiscalYear") int fiscalYear) {
    // 业务逻辑实现
}

3. 排查Response类的序列化问题 #

Spring Boot 3.x使用Jackson 2.15+版本，对Java Bean的序列化要求更严格：

• 确保Response类有无参构造方法
• 需要序列化的字段要有公开的getter方法，或添加@JsonProperty注解指定字段
• 查看控制台的异常栈信息，直接定位是否为序列化失败导致的500错误

二、Swagger参数不显示及Try it out失效问题解决 #

Spring Boot 3.x不再支持原有的Springfox Swagger依赖，必须改用SpringDoc OpenAPI：

1. 移除旧的Springfox依赖 #

在pom.xml中删除所有springfox-swagger2、springfox-swagger-ui相关依赖

2. 添加SpringDoc OpenAPI依赖 #

引入适配Spring Boot 3.x的版本：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

（版本可选择与Spring Boot 3.2.1兼容的最新稳定版）

3. 可选：自定义Swagger配置 #

如果需要分组管理接口或自定义文档内容，可添加配置类：

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public GroupedOpenApi accountApi() {
        return GroupedOpenApi.builder()
                .group("account-api")
                .pathsToMatch("/api/account/**")
                .build();
    }
}

4. 访问Swagger UI #

启动项目后，访问http://localhost:8080/swagger-ui.html，此时应能正常显示fiscalYear参数并使用Try it out功能

三、通用排查建议 #

• 优先查看控制台的错误日志，500错误的具体异常栈是定位问题最直接的依据
• 确认所有依赖都已升级到适配Spring Boot 3.2.1的版本，避免依赖冲突
• 先用Postman等工具直接调用接口，排除Swagger本身的干扰，确认接口功能是否正常

内容的提问来源于stack exchange，提问作者Nanda