同HTTP状态码多业务异常的OpenAPI规范及SpringDoc实现问询

当然有更标准的实现方式，核心是在OpenAPI规范中明确为400状态码的响应绑定统一异常Schema，并通过多示例枚举所有可能的业务异常场景，既符合规范又能清晰展示每个异常的细节。以下是springdoc-openapi的两种实现方式：

方式1：接口方法直接配置响应示例 #

在接口方法上通过注解直接定义400响应的统一Schema和多个业务异常示例：

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @GetMapping("/{orderId}")
    @Operation(summary = "获取订单详情")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "成功获取订单"),
            @ApiResponse(responseCode = "400", description = "业务异常",
                    content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = BusinessErrorResponse.class),
                            examples = {
                                    @ExampleObject(
                                            name = "订单不存在",
                                            summary = "订单ID不存在",
                                            value = "{\"errorCode\":\"ORDER_NOT_FOUND\",\"message\":\"指定的订单不存在\",\"errorParam\":\"orderId=123\"}"
                                    ),
                                    @ExampleObject(
                                            name = "订单已关闭",
                                            summary = "订单状态不可操作",
                                            value = "{\"errorCode\":\"ORDER_CLOSED\",\"message\":\"该订单已关闭，无法查询\",\"errorParam\":\"orderId=456\"}"
                                    ),
                                    @ExampleObject(
                                            name = "参数格式错误",
                                            summary = "订单ID格式非法",
                                            value = "{\"errorCode\":\"PARAM_FORMAT_INVALID\",\"message\":\"订单ID必须为数字\",\"errorParam\":\"orderId=abc\"}"
                                    )
                            }
                    )
            )
    })
    public OrderDto getOrder(@PathVariable String orderId) {
        // 业务逻辑实现
    }
}

// 统一业务异常响应类
@Schema(description = "业务异常响应结构")
public class BusinessErrorResponse {
    @Schema(description = "业务错误码")
    private String errorCode;
    @Schema(description = "错误提示信息")
    private String message;
    @Schema(description = "错误关联的参数信息")
    private String errorParam;

    // getter、setter及构造方法
}

方式2：全局配置复用异常响应模板 #

如果多个接口存在相同的400业务异常场景，可以通过全局配置类统一注册响应模板，避免重复代码：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        // 定义统一的业务异常Schema
        Schema<BusinessErrorResponse> errorSchema = new Schema<>();
        errorSchema.addProperty("errorCode", new StringSchema().description("业务错误码"));
        errorSchema.addProperty("message", new StringSchema().description("错误提示信息"));
        errorSchema.addProperty("errorParam", new StringSchema().description("错误关联参数"));

        // 构建各业务异常示例
        Example orderNotFoundExample = new Example()
                .summary("订单不存在")
                .description("请求的订单ID未在系统中找到")
                .value(Map.of(
                        "errorCode", "ORDER_NOT_FOUND",
                        "message", "指定的订单不存在",
                        "errorParam", "orderId=123"
                ));

        Example orderClosedExample = new Example()
                .summary("订单已关闭")
                .description("订单处于关闭状态，无法执行查询操作")
                .value(Map.of(
                        "errorCode", "ORDER_CLOSED",
                        "message", "该订单已关闭，无法查询",
                        "errorParam", "orderId=456"
                ));

        // 组装400响应模板
        ApiResponse badRequestResponse = new ApiResponse()
                .description("业务异常")
                .content(Map.of(
                        MediaType.APPLICATION_JSON_VALUE, new Content()
                                .schema(errorSchema)
                                .examples(Map.of(
                                        "ORDER_NOT_FOUND", orderNotFoundExample,
                                        "ORDER_CLOSED", orderClosedExample
                                ))
                ));

        return new OpenAPI()
                .info(new Info().title("订单服务API").version("v1"))
                .components(new Components()
                        .addResponses("BadRequestBusinessErrors", badRequestResponse));
    }
}

之后在接口方法中直接引用全局定义的响应模板：

@GetMapping("/{orderId}")
@Operation(summary = "获取订单详情")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功获取订单"),
        @ApiResponse(responseCode = "400", ref = "#/components/responses/BadRequestBusinessErrors")
})
public OrderDto getOrder(@PathVariable String orderId) {
    // 业务逻辑实现
}

不需要特意为每个业务异常创建独立Schema，理由如下：

1. 复用性优先：所有400业务异常的结构完全统一（包含errorCode、message、errorParam），复用同一个Schema能减少冗余，符合DRY原则。
2. 适配场景需求：OpenAPI V3的anyOf/oneOf特性是为了解决响应结构不一致的场景（比如同一状态码下可能返回两种完全不同的JSON结构），而你的场景只是字段值不同、结构完全一致，用「统一Schema + 多示例」的方式更贴合需求。
3. 维护与可读性更强：统一Schema能让开发者快速理解异常响应的固定结构，多示例则清晰展示每种业务场景的具体返回值，比创建多个结构重复的Schema更易维护，也方便前端统一解析异常逻辑（只需根据errorCode分支处理即可）。

强行使用oneOf搭配多个Schema反而会让API文档臃肿，增加不必要的维护成本。

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