Swagger UI合并同路径多端点，强制参数为required问题求助

OpenAPI（Swagger依赖的规范）会将相同HTTP方法、相同路径的接口判定为同一个操作，不管参数或安全配置是否不同，这就是两个端点被合并的根本原因。以下是两种可行的解决方法：

方法1：修改路径，让两个端点独立（推荐） #

直接给两个接口设置不同的路径，从根源上避免Swagger合并：

@GetMapping("/api/entity")
@SecurityRequirement(name = "Basic Authentication")
public List<EntityResponseDTO> getAll() { 
    return entityService.getEntities(); 
}

// 修改路径，明确区分按城市查询的接口
@GetMapping("/api/entity/by-city")
public List<EntityResponseDTO> getAllInCity(@RequestParam("city") String city) { 
    return entityService.getEntities(city); 
}

这样Swagger UI会显示两个独立的GET端点：

• /api/entity：带Basic Auth要求，无请求参数，供授权用户查询所有实体
• /api/entity/by-city：无安全要求，必填city参数，供未登录用户查询指定城市的实体

方法2：保留同路径，用operationId强制区分 #

如果业务上必须保留相同路径，可以通过给两个接口指定唯一的operationId，让Swagger识别为不同操作：

@GetMapping("/api/entity")
@SecurityRequirement(name = "Basic Authentication")
@Operation(operationId = "getAllEntities") // 唯一操作ID
public List<EntityResponseDTO> getAll() { 
    return entityService.getEntities(); 
}

@GetMapping("/api/entity")
@Operation(operationId = "getEntitiesByCity") // 唯一操作ID
public List<EntityResponseDTO> getAllInCity(
    @Parameter(required = true) @RequestParam("city") String city) { 
    return entityService.getEntities(city); 
}

注意：部分Swagger版本对同路径不同operationId的支持存在兼容性问题，如果合并问题仍未解决，优先使用方法1。

额外验证：确保安全配置生效 #

确认Swagger的安全方案已正确定义，比如在配置类或启动类上添加：

@OpenAPIDefinition
@SecurityScheme(
    name = "Basic Authentication",
    type = SecuritySchemeType.HTTP,
    scheme = "basic"
)

这样带@SecurityRequirement的端点会在Swagger UI显示授权入口，不带的则无需授权即可调用。

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