SpringBoot @PathVariable异常：Swagger无参数框+反射报错

核心原因 #

异常信息已经明确指出：Java编译时未保留方法参数名，导致Spring无法通过反射获取@PathVariable对应的参数名称。

默认情况下，Java编译器不会将方法的原始参数名编译到class文件中，Spring在处理未显式指定value/name属性的@PathVariable时，需要通过反射获取参数名来匹配URL路径中的占位符。如果没有参数名信息，就会抛出这个IllegalArgumentException。

你的另一个同结构项目能正常运行，大概率是因为它的编译配置中添加了-parameters编译选项，该选项会让编译器保留原始参数名到class文件中。

解决方案 #

方案1：添加编译参数-parameters #

这是根治问题的方式，确保编译时保留参数名：

Maven项目（修改pom.xml）

在maven-compiler-plugin中添加编译器参数：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version> <!-- 版本可根据你的项目调整 -->
            <configuration>
                <source>17</source> <!-- 对应你的JDK版本 -->
                <target>17</target>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle项目（修改build.gradle）

添加编译参数配置：

tasks.withType(JavaCompile) {
    options.compilerArgs << '-parameters'
}

配置完成后，执行clean compile重新编译项目，问题即可解决，Swagger也会正常显示@PathVariable的参数输入框。

方案2：显式指定@PathVariable的参数名 #

如果暂时不想调整编译配置，可以给@PathVariable显式指定匹配的路径占位符名称，比如：

@GetMapping(value = "/id/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
public DavinciApiResponse<CurrencyDTO> findById(@PathVariable("id") Integer id) {
    return currencyInboundAdapterRestImpl.findById(id);
}

@GetMapping(value = "/code/{code}", produces = MediaType.APPLICATION_JSON_VALUE)
public DavinciApiResponse<CurrencyDTO> findByCode(@PathVariable("code") String code) {
    return currencyInboundAdapterRestImpl.findByCode(code);
}

这种方式不需要依赖编译时的参数名信息，Spring会直接使用你指定的名称匹配路径占位符，同时Swagger也能识别到参数。

补充说明 #

移除@PathVariable后仍报错，是因为Spring会把该参数视为请求参数（@RequestParam），但同样需要获取参数名，还是会触发相同的反射问题。只有解决参数名可获取的问题，才能彻底消除报错。

内容的提问来源于stack exchange，提问作者Paul Marcelin Bejan