@ApiResponse用于描述接口各HTTP状态码的响应结构，需配合ErrorResponse类和@ControllerAdvice实现文档与实际响应一致。
在 Spring Boot 项目中使用 Springdoc（替代旧版 Swagger）时，@ApiResponse 主要用于描述接口的**成功响应**，它本身不直接支持“声明自定义异常响应”——因为异常响应通常不是接口方法的显式返回值，而是由全局异常处理器（如 @ControllerAdvice）统一处理并返回的。但你可以通过组合注解，让文档清晰展示可能抛出的异常 HTTP 状态码和响应体结构。
✅ 正确理解 @ApiResponse 的定位
@ApiResponse 是 OpenAPI 规范的一部分，作用是为某个 HTTP 状态码（如 200、400、500）提供响应描述。它不绑定 Java 异常类，而是绑定 HTTP 状态码 + 响应体 Schema。所以你要做的不是“声明抛了哪个 Exception”，而是“这个接口在某种错误情况下会返回什么 HTTP 状态和 JSON 结构”。
✅ 用 @ApiResponse 描述常见异常状态（如 400/404/500）
在 Controller 方法上，用多个 @ApiResponse 显式标注不同状态码的响应：
@Operation(summary = "根据ID查询用户")
@ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "400", description = "请求参数无效", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@ApiResponse(responseCode = "404", description = "用户不存在", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@ApiResponse(responseCode = "500", description = "服务器内部错误", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) { ... }
-
@Operation是顶层描述，推荐配合使用 -
responseCode必须是字符串（如 "400"），不能写 400 -
content.schema.implementation指向你定义的统一错误响应类（如ErrorResponse），确保其字段有@Schema注解或 Lombok@Data+@Schema支持
✅ 定义统一的 ErrorResponse 类（供文档引用）
让所有异常响应体结构一致，便于文档生成和前端解析：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
立即学习“Java免费学习笔记（深入）”；
public class ErrorResponse {
@Schema(description = "HTTP 状态码", example = "404")
private int status;
@Schema(description = "业务错误码", example = "USER_NOT_FOUND")
private String code;
@Schema(description = "错误信息", example = "用户不存在")
private String message;
@Schema(description = "时间戳", example = "2024-06-15T10:20:30Z")
private Instant timestamp;
// 构造函数 / getter / setter
}
Springdoc 会自动识别该类字段并渲染到对应状态码的响应示例中。
✅ 配合全局异常处理器，确保实际返回匹配文档
文档只是说明，真实响应需由 @ControllerAdvice 统一输出符合 ErrorResponse 结构的 JSON：
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException e) {
ErrorResponse error = new ErrorResponse(404, "USER_NOT_FOUND", e.getMessage(), Instant.now());
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException e) {
String message = e.getBindingResult().getFieldErrors().get(0).getDefaultMessage();
ErrorResponse error = new ErrorResponse(400, "VALIDATION_FAILED", message, Instant.now());
return ResponseEntity.badRequest().body(error);
}
}
- 每个
@ExceptionHandler返回的ErrorResponse实例，必须与@ApiResponse中指定的implementation类型一致 - 状态码（
ResponseEntity.status(...)）必须与@ApiResponse.responseCode对应，否则文档和实际不符
不复杂但容易忽略：文档和代码要双向对齐——写了 @ApiResponse 就得真返回；返回了某种错误结构，就该在接口上声明清楚。
