Java SpringBoot OpenApi @ApiResponse非200状态码返回错误对象问题

这不是Swagger的Bug，是springdoc-openapi-ui1.5.12版本的默认机制导致的，具体原因和解决方法如下：

问题原因 #

• 该版本的springdoc-openapi默认开启了响应类型继承逻辑：当你在接口上通过produces = {"application/json"}指定了返回媒体类型，且接口方法的返回值明确为List<LetterDTO>时，所有没有显式配置@Content属性的@ApiResponse，会默认继承方法级别的返回类型作为响应结构。
• 你看到的400状态码返回默认错误结构，是因为项目中大概率已经通过@ControllerAdvice做了全局参数异常处理，且springdoc识别到了400状态码的全局响应配置，所以没有继承方法返回类型；而401、403、404这类状态码没有对应全局OpenApi响应配置，所以触发了继承逻辑，复用了200状态码的返回结构。

解决方法 #

方案1：单独为异常响应配置content（推荐） #

针对不需要返回业务对象的状态码，显式指定content = @Content即可关闭继承，示例代码如下：

@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "success", content = {@Content(
                                                                    mediaType = "application/json",
                                                                    array = @ArraySchema(schema = @Schema(implementation = LetterDTO.class)))}),
        @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
        @ApiResponse(responseCode = "401", description = "UNAUTHORIZED", content = @Content),
        @ApiResponse(responseCode = "403", description = "Forbidden", content = @Content),
        @ApiResponse(responseCode = "404", description = "NOT_FOUND: Entity could not be found", content = @Content)}
)

如果你想要这些异常码返回统一的错误结构，也可以先定义通用的ErrorDTO类，再将其配置为对应响应的schema：

@ApiResponse(responseCode = "401", description = "UNAUTHORIZED", content = {@Content(
        mediaType = "application/json",
        schema = @Schema(implementation = ErrorDTO.class)
)})

方案2：全局关闭响应类型继承 #

在application.yml中添加如下配置，即可关闭全局的响应类型继承逻辑：

springdoc:
  override-with-generic-response: false

该配置会让所有没有显式配置content的响应都不继承方法返回类型，但可能会导致部分正常响应的结构识别失效，因此更推荐使用方案1。

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