Java中自定义异常要被Swagger识别，需三步协同：定义带@Schema的ErrorResponse类、在接口用@ApiResponse声明各状态码响应、配@ControllerAdvice全局统一返回格式。
Java 中自定义异常要真正“被 Swagger 看见”，关键不是只抛出异常，而是让 Springdoc（或 springfox）能把异常映射为 OpenAPI 文档里的 responses。这需要三步协同：定义可描述的异常模型、在接口上显式声明错误响应、并通过全局异常处理器确保运行时返回格式统一。
用 @Schema 定义 ErrorResponse 类
Swagger 不会自动把 RuntimeException 子类转成文档结构，必须提供一个带语义的错误响应体类，并用 @Schema 明确标注：
- 类加
@Schema(description = "通用错误响应") - 每个字段加
@Schema(description = "...", example = "...")，比如code、message、timestamp - 如果用了 Lombok，确保
@Data或手动提供 getter/setter，否则字段可能不被扫描到 - 避免字段名与 OpenAPI 关键字冲突（如不要叫
schema或responses）
在接口方法上用 @ApiResponse 声明具体错误码
@Operation 描述整体行为，而每个可能的 HTTP 错误码需单独用 @ApiResponse 绑定到你的 ErrorResponse：
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
-
responseCode必须是字符串，如"400"，不能写400 -
content = @Content(schema = @Schema(implementation = ErrorResponse.class))是核心，告诉 Swagger 这个状态码返回什么结构 - 建议覆盖常见错误：400（参数校验失败）、401/403（认证鉴权）、404（资源不存在）、500（服务异常）
- 多个
@ApiResponse可并列写在同一个方法上，无需@ApiResponses包裹（Springdoc 1.6+ 支持直接重复注解）
配合同步的 @RestControllerAdvice 全局处理
文档里写了 400，但运行时抛 MethodArgumentNotValidException 却返回了默认白页或堆栈，说明没接住。全局异常处理器要干两件事：
立即学习“Java免费学习笔记（深入）”；
- 捕获具体异常类型（如
MethodArgumentNotValidException、自定义的BusinessException），转换为标准ErrorResponse实例 - 设置对应 HTTP 状态码：
@ResponseStatus(HttpStatus.BAD_REQUEST)或在ResponseEntity中显式指定 - 确保该处理器类被 Spring 扫描到（加
@Component或@RestControllerAdvice） - 如果自定义异常本身带状态码字段（如
private int code = 500），可在处理器中读取并动态设状态码
验证是否生效的小技巧
启动项目后访问 /v3/api-docs（Springdoc 默认路径），搜索你的接口路径，看 responses 字段下是否有你声明的 "400"、"404" 等对象；再打开 Swagger UI 页面，点开对应接口的 “Try it out”，展开 “Responses” 区域，确认错误响应结构已渲染出来且字段可读。
