如何在Swagger UI中区分两个仅参数不同的@GetMapping端点

问题原因 #

SpringDoc默认会将同路径、同HTTP请求方法的接口合并展示，即便接口通过params属性区分了调用条件，Swagger UI仍会把它们合并为一个条目。

解决方案：为每个接口指定唯一operationId #

通过SpringDoc提供的@Operation注解，为两个接口设置不同的operationId，让Swagger UI识别为独立的接口。

修改后的代码示例如下：

import io.swagger.v3.oas.annotations.Operation;

@GetMapping
@Operation(operationId = "getAllTasks")
public ResponseEntity<Response> getAll() {
    List<Task> tasks = service.findAll();
    Response response = TaskGetListResponse.success(tasks);
    return convert(response);
}

@GetMapping(params = "name")
@Operation(operationId = "getTasksByName")
public ResponseEntity<Response> getByName(String name) {
    List<Task> tasks = service.findSoftlyByName(name);
    Response response = TaskGetListResponse.success(tasks);
    return convert(response);
}

补充说明 #

• 若使用旧版Springfox（Swagger 2），可改用@ApiOperation的nickname属性实现相同效果，但你当前依赖的是SpringDoc（OpenAPI 3），优先使用@Operation的operationId更符合规范。
• 也可通过配置文件调整合并策略，但不推荐全局禁用，可能影响其他接口的正常展示：

  springdoc.api-docs.merge-with-existing=false
  

  相比之下，为每个接口设置唯一operationId是更精准、通用的处理方式。

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