要让Swagger正确展示Java自定义异常的错误码，需三步：定义带@Schema注解的ErrorResponse类；在接口用@ApiResponses声明各HTTP状态码对应的ErrorResponse响应；通过@ControllerAdvice全局处理器将自定义异常转为含code/message的ErrorResponse并匹配对应状态码返回。
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 = "...")写在字段上）
示例：
立即学习“Java免费学习笔记（深入）”；
@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重复写
示例：
立即学习“Java免费学习笔记（深入）”；
@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) {
// ...
}
全局异常处理器里返回 ErrorResponse（让运行时也生效）
Swagger 文档只是“说明”，真正调用时前端看到的错误响应，取决于你的全局异常处理器怎么封装返回值。
- 用
@ControllerAdvice拦截自定义异常（如BusinessException） - 在处理方法中，把异常里的
errorCode和message填进ErrorResponse实例，再用ResponseEntity.status(xxx).body(...)返回 - HTTP 状态码要和你在
@ApiResponse中声明的一致（比如抛BusinessException对应 400，就用HttpStatus.BAD_REQUEST）
这样，Swagger 文档写的“404 返回 ErrorResponse”，和真实请求返回的 JSON 结构就完全一致了。
错误码字段怎么进 ErrorResponse？靠异常类自己提供
Swagger 不读取异常类的字段，但它依赖你全局处理器的逻辑。所以你的自定义异常类（如 BusinessException）最好自带 getErrorCode() 和 getMessage() 方法：
- 推荐用枚举管理错误码（如
ErrorCode.USER_NOT_FOUND），异常构造时传入枚举，内部自动提取code和默认message - 全局处理器拿到异常后，调用
e.getErrorCode()和e.getMessage()，组装成ErrorResponse即可
这样，代码逻辑、文档描述、实际响应三者就对齐了——前端看文档知道字段含义，调接口拿到的 JSON 也真有那些字段。
