Java 自定义异常怎么配合 Swagger 展示错误码-java教程-PHP中文网

要让swagger正确展示java自定义异常的错误码，需三步：定义带@schema注解的errorresponse类；在接口用@apiresponses声明各http状态码对应的errorresponse响应；通过@controlleradvice全局处理器将自定义异常转为含code/message的errorresponse并匹配对应状态码返回。

java 自定义异常怎么配合 swagger 展示错误码

Java 自定义异常要让 Swagger（Springdoc）正确展示错误码，关键不是“抛出异常”，而是“告诉 Swagger 这个异常对应什么 HTTP 状态码、返回什么结构体”。这需要三步配合：定义统一错误响应体、在接口上声明异常响应、确保异常类本身可被识别（通常不需要额外注解）。

定义标准 ErrorResponse 类（Swagger 能识别的返回结构）

Swagger 生成文档时，只认你明确标注了 @Schema 的 Java 类。它不关心你抛的是哪个异常类，只关心你告诉它“400 错误会返回什么 JSON”。

所以先写一个清晰、带 OpenAPI 注解的错误响应类：

必须加 @Schema 注解，描述整体用途；字段也要有 @Schema，否则 Swagger 可能忽略或显示为 unknown
推荐包含 code（业务错误码，如 "USER_NOT_FOUND"）、message（提示语）、timestamp（时间戳）等字段
用 Lombok @Data 可省 getter/setter，但别忘了加上 @Schema 支持（例如 @Schema(description = "...") 写在字段上）

示例：

@Schema(description = "统一错误响应格式")
public class ErrorResponse {
    @Schema(description = "业务错误码", example = "AUTH_TOKEN_EXPIRED")
    private String code;

    @Schema(description = "用户提示消息", example = "登录已过期，请重新登录")
    private String message;

    @Schema(description = "错误发生时间", implementation = Instant.class)
    private Instant timestamp;

    // 构造方法、getter/setter（略）
}

在 Controller 接口上用 @ApiResponse 声明异常响应

Swagger 不会自动扫描你抛了哪些自定义异常，必须显式告诉它：“这个接口可能返回 400，响应体是 ErrorResponse”。

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

用 @Operation 描述接口，再用 @ApiResponse 列出每个可能的 HTTP 状态码和对应响应体
responseCode 必须是字符串，比如 "400"，不能写 400
content = @Content(schema = @Schema(implementation = ErrorResponse.class)) 这一句最关键，把错误结构绑定上去
建议用 @ApiResponses 批量声明常见错误（400/404/500），避免每个 @ApiResponse 重复写

示例：

@Operation(summary = "根据ID查询用户")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "成功"),
    @ApiResponse(
        responseCode = "404",
        description = "用户不存在",
        content = @Content(schema = @Schema(implementation = ErrorResponse.class))
    ),
    @ApiResponse(
        responseCode = "400",
        description = "参数校验失败",
        content = @Content(schema = @Schema(implementation = ErrorResponse.class))
    )
})
@GetMapping("/users/{id}")
public ResponseEntity<user> getUserById(@PathVariable Long id) {
    // ...
}</user>

全局异常处理器里返回 ErrorResponse（让运行时也生效）

Swagger 文档只是“说明”，真正调用时前端看到的错误响应，取决于你的全局异常处理器怎么封装返回值。

用 @ControllerAdvice 拦截自定义异常（如 BusinessException）
在处理方法中，把异常里的 errorCode 和 message 填进 ErrorResponse 实例，再用 ResponseEntity.status(xxx).body(...) 返回
HTTP 状态码要和你在 @ApiResponse 中声明的一致（比如抛 BusinessException 对应 400，就用 HttpStatus.BAD_REQUEST）