Java中接口 API 文档 Swagger/Springdoc 怎么用 @ApiResponse 声明自定义异常响应-java教程-PHP中文网

@apiresponse用于描述接口各http状态码的响应结构，需配合errorresponse类和@controlleradvice实现文档与实际响应一致。

java中接口 api 文档 swagger/springdoc 怎么用 @apiresponse 声明自定义异常响应

在 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) { ... }
</user>

@Operation 是顶层描述，推荐配合使用
responseCode 必须是字符串（如 "400"），不能写 400
content.schema.implementation 指向你定义的统一错误响应类（如 ErrorResponse），确保其字段有 @Schema 注解或 Lombok @Data + @Schema 支持

✅ 定义统一的 ErrorResponse 类（供文档引用）

让所有异常响应体结构一致，便于文档生成和前端解析：

deep-java-review

Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...

下载

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);
    }
}
</errorresponse></errorresponse>

每个 @ExceptionHandler 返回的 ErrorResponse 实例，必须与 @ApiResponse 中指定的 implementation 类型一致
状态码（ResponseEntity.status(...)）必须与 @ApiResponse.responseCode 对应，否则文档和实际不符

不复杂但容易忽略：文档和代码要双向对齐——写了 @ApiResponse 就得真返回；返回了某种错误结构，就该在接口上声明清楚。