Spring Boot 3 OpenAPI 全局错误响应码配置方案求助

要在Spring Boot 3的OpenAPI（Swagger 3）中全局配置通用HTTP响应状态码，无需在每个端点重复编写@ApiResponses，可以通过自定义OperationCustomizer实现，同时保留默认的200成功响应。

修改后的OpenApiConfig配置类 #

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI usersMicroserviceOpenAPI() {
        Server localServer = new Server()
                .url("http://localhost:8080")
                .description("A Server URL");

        Contact contact = new Contact()
                .email("hi@example.com")
                .name("Exampl man");

        Info info = new Info()
                .contact(contact)
                .description("Spring Boot 3 + Open API 3")
                .summary("Demo of Spring Boot 3 & Open API 3 Integration")
                .title("Sample")
                .version("V1.0.0")
                .license(new License().name("Apache 2.0").url("http://springdoc.org"));

        return new OpenAPI().info(info)
                .addServersItem(localServer);
    }

    // 全局响应状态码自定义处理器
    @Bean
    public OperationCustomizer globalResponseCustomizer() {
        return (operation, handlerMethod) -> {
            // 构建通用错误响应内容
            Content errorContent = new Content()
                    .addMediaType(MediaType.APPLICATION_JSON_VALUE, 
                        new MediaType().schema(new Schema<ErrorRes>().implementation(ErrorRes.class)));

            // 添加400 Bad Request响应
            operation.getResponses().addApiResponse("400", 
                new ApiResponse().description("Bad Request").content(errorContent));

            // 添加404 Not Found响应
            operation.getResponses().addApiResponse("404", 
                new ApiResponse().description("Resource Not Found").content(errorContent));

            // 保留默认200成功响应（若接口未显式定义）
            if (!operation.getResponses().containsKey("200")) {
                operation.getResponses().addApiResponse("200", new ApiResponse().description("Success"));
            }

            return operation;
        };
    }
}

实现说明 #

• OperationCustomizer是springdoc提供的扩展接口，允许对每个API接口的Operation元数据进行自定义修改。
• 代码中先构建了通用的错误响应结构（绑定ErrorRes类），然后为所有接口统一添加400和404状态码的响应配置。
• 最后检查并补充默认的200成功响应，避免因全局配置覆盖默认的成功状态码说明。

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