Spring Boot集成Swagger 3时同端点多参数API不显示问题求助

问题原因 #

Swagger/OpenAPI规范要求相同路径+相同HTTP方法的接口必须通过唯一的operationId来区分。默认情况下，springdoc生成operationId时未将请求参数的差异纳入考量，导致多个同路径不同参数的GET接口被识别为同一个操作，仅显示其中一个。

解决方案 #

方案一：配置自动生成唯一operationId #

在配置文件（application.properties或application.yml）中添加以下配置，让springdoc基于方法名和请求参数生成唯一的operationId：

properties格式：

springdoc.api-docs.operation-id-strategy=METHOD_NAME_WITH_PARAMS

yaml格式：

springdoc:
  api-docs:
    operation-id-strategy: METHOD_NAME_WITH_PARAMS

该配置会让springdoc为每个不同参数组合的接口生成独一无二的operationId，Swagger UI即可区分所有接口。

方案二：手动指定唯一operationId #

通过@Operation注解为每个接口手动设置唯一的operationId，确保Swagger能识别为不同操作：

修改接口代码：

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

@RequestMapping(value = "/title/find", params= {"provider", "offerEnd"}, method = RequestMethod.GET)
@Operation(operationId = "findTitleByProviderAndOfferEnd")
public List<Title> AMethodName(@RequestParam final String provider, @RequestParam final String offerEnd) {
    // 业务逻辑实现
} 

@RequestMapping(value = "/title/find", params = {"channel","offerStart"}, method = RequestMethod.GET)
@Operation(operationId = "findTitleByChannelAndOfferStart")
public List<Title> BMethodName(@RequestParam final String channel, @RequestParam final List<String> offerStart) {
    // 业务逻辑实现
}

@RequestMapping(value = "/title/find", params= {"provider","offerStart","titleBrief"}, method = RequestMethod.GET)
@Operation(operationId = "findTitleByProviderOfferStartAndTitleBrief")
public List<Title> CMethodName(@RequestParam final List<String> provider, @RequestParam final List<String> offerStart, @RequestParam final String titleBrief) {
    // 业务逻辑实现
}

方案三：升级springdoc版本（可选） #

若上述配置无效，可尝试升级springdoc-openapi-ui至兼容Spring Boot 2.6.8的更高版本（如1.6.14），新版本优化了同路径不同参数接口的识别逻辑：

修改pom.xml依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

验证 #

重启应用后访问Swagger UI页面，三个/title/find接口将分别展示，可查看各自的参数定义。

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