Spring Boot中Swagger仅展示同路径单端点，求多Consumes端点显示方案

Swagger（OpenAPI）默认会合并路径、HTTP方法完全相同的端点，仅靠@Consumes标签区分时，旧版本的Swagger工具（比如Springfox）无法识别为独立操作，导致只显示靠前的端点。以下是可行的解决方法：

1. 升级到SpringDoc OpenAPI（推荐） #

Springfox已停止维护，SpringDoc对OpenAPI规范的支持更完善，能正确识别通过consumes/produces区分的端点。

依赖配置 #

• Spring Boot 3 项目：

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

• Spring Boot 2 项目：

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

配置完成后重启应用，Swagger UI会自动识别两个不同Consumes的端点。

2. 显式设置唯一operationId #

给两个端点设置不同的operationId，强制Swagger将它们识别为独立操作。修改Controller代码：

@RestController
@RequestMapping("/your-api-path")
public class YourController {

    @Deprecated
    @PostMapping
    @Consumes(MediaType.APPLICATION_JSON_VALUE)
    @Operation(operationId = "deprecatedEndpointJson", summary = "已废弃端点（JSON格式）")
    public ResponseEntity<String> deprecatedEndpoint(@RequestBody YourRequest request) {
        // 业务逻辑
        return ResponseEntity.ok("deprecated response");
    }

    @PostMapping
    @Consumes(MediaType.MULTIPART_FORM_DATA_VALUE)
    @Operation(operationId = "activeEndpointMultipart", summary = "当前生效端点（表单格式）")
    public ResponseEntity<String> activeEndpoint(@RequestParam("param") String param) {
        // 业务逻辑
        return ResponseEntity.ok("active response");
    }
}

3. 确保@Consumes媒体类型无重叠 #

确认两个端点的@Consumes指定的媒体类型完全不同，比如一个用application/json，另一个用multipart/form-data或application/x-www-form-urlencoded，避免Swagger因媒体类型模糊而合并端点。

4. Springfox自定义插件（仅兼容旧项目） #

如果无法升级到SpringDoc，可自定义Swagger插件，基于consumes条件生成唯一标识：

@Component
public class ConsumesDistinctPlugin implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        Set<String> consumes = context.getRequestMappingInfo().getConsumesCondition().getConsumes();
        String operationId = context.operationBuilder().build().getOperationId();
        // 给operationId加上媒体类型后缀，确保唯一性
        context.operationBuilder().operationId(operationId + "_" + String.join("_", consumes));
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return DocumentationType.SWAGGER_2.equals(documentationType);
    }
}

完成上述配置后，Swagger UI会同时展示两个端点，且能区分它们的媒体类型差异。

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