Spring Boot中同RequestMapping不同参数的Endpoint在Swagger UI不显示

问题原因 #

Swagger（尤其是Springfox早期版本）对通过params属性区分的同路径、同HTTP方法的接口，默认会将它们判定为同一个操作，导致接口无法单独显示、参数混叠。

解决方案 #

1. 为每个接口指定唯一的operationId #

通过Swagger的@Operation注解给每个接口设置唯一的操作ID，强制Swagger区分不同接口：

@RequestMapping(value = "/deposits")
public class DepositController {

    @GetMapping(params = "idDepositSignal")
    @Operation(operationId = "adviseDepositByIds")
    public ResponseEntity<Boolean> adviseDeposit(@RequestParam List<Long> idDepositSignal) {
        return new ResponseEntity<>(depositService.adviceDeposit(idDepositSignal), HttpStatus.OK);
    }

    @GetMapping(params = "idDepositDuplicate")
    @Operation(operationId = "duplicateDepositById")
    public ResponseEntity<Deposit> duplicateDeposit(@RequestParam Long idDepositDuplicate) {
        return new ResponseEntity<>(depositService.duplicateDeposit(idDepositDuplicate), HttpStatus.OK);
    }
}

2. 替换为SpringDoc（推荐） #

如果使用的是Springfox，建议替换为SpringDoc OpenAPI，它对Spring Boot的新特性（包括params路由匹配）支持更完善：

• 添加Maven依赖（适配你的Spring Boot版本）：

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

• 启动项目后访问/swagger-ui.html，带params的接口会自动正确区分显示，无需额外复杂配置。

3. 显式声明参数规则（可选） #

配合@Parameter注解明确参数的作用，让Swagger文档更清晰：

@GetMapping(params = "idDepositSignal")
@Operation(operationId = "adviseDepositByIds")
public ResponseEntity<Boolean> adviseDeposit(
        @Parameter(description = "存款信号ID列表", required = true) 
        @RequestParam List<Long> idDepositSignal) {
    return new ResponseEntity<>(depositService.adviceDeposit(idDepositSignal), HttpStatus.OK);
}

补充说明 #

对于另一个Controller中的/deposits/{depositId}接口，由于路径包含PathVariable，Swagger通常能正确识别，但如果仍出现合并问题，同样可以添加唯一的operationId来避免冲突。

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