Spring Boot集成Swagger添加异常处理器后出现Failed to load API definition. Response status is 500 /v3/api-docs错误

嘿，我完全懂你遇到的困扰——原本运行好好的Spring Boot银行项目，API、Swagger UI、Postman测试都没问题，结果加了异常处理器之后，Swagger突然就加载失败，报500错误说没法加载API定义对吧？别慌，咱们一步步排查解决。

最可能的原因：自定义异常处理器拦截了Swagger的请求 #

你添加的全局异常处理器（比如带@RestControllerAdvice或@ControllerAdvice的类），很可能捕获了Swagger生成/v3/api-docs文档时抛出的内部异常，而你的处理逻辑没有适配Swagger的需求，导致返回的响应不符合它的解析要求，直接触发了500错误。

具体解决办法 #

1. 在异常处理器中排除Swagger相关路径
   在你的异常处理方法里，先判断当前请求的URI是否属于Swagger的路径，如果是，就直接抛出异常，交给Spring默认的处理逻辑来处理，不要用自定义的响应格式。举个代码例子：

   @RestControllerAdvice
   public class GlobalExceptionHandler {
   
       @ExceptionHandler(Exception.class)
       public ResponseEntity<ErrorResponse> handleAllExceptions(Exception ex, HttpServletRequest request) {
           // 排除Swagger相关请求
           if (request.getRequestURI().contains("/v3/api-docs") || request.getRequestURI().contains("/swagger-ui")) {
               throw ex; // 交给Spring默认处理
           }
           // 你的自定义异常处理逻辑
           ErrorResponse error = new ErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(), ex.getMessage());
           return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
       }
   }
   

2. 排查控制台的具体错误日志
   你可以看下项目启动后的控制台日志，找到500错误对应的堆栈信息，看看具体是哪个异常被触发了。比如可能是Swagger在扫描API时抛出了某个反射相关的异常，被你的处理器捕获后处理不当，根据具体异常调整处理逻辑会更精准。

3. 检查异常响应的序列化问题
   如果你的自定义异常响应体（比如上面的ErrorResponse类）存在序列化问题（比如没有无参构造器、字段没有getter方法），也可能导致Swagger无法解析响应，进而触发500。确保你的响应实体类是标准的可序列化Bean。

测试验证 #

修改完异常处理器后，重启项目，先直接访问/v3/api-docs路径，看看能不能正常返回JSON格式的API文档。如果能正常返回，再打开Swagger UI，应该就能正常加载所有端点了。

备注：内容来源于stack exchange，提问作者Vijay Mohan Rangaraju