Swagger无法识别ResponseEntity返回类型怎么解决

本文旨在解决在使用Spring `ResponseEntity`返回API响应时，Swagger无法正确识别并生成预期数据模型的问题。核心在于当`ResponseEntity`未指定泛型类型时，Swagger难以推断实际响应结构。通过为`ResponseEntity`明确指定泛型类型，并合理处理不同HTTP状态下的响应体，我们可以确保Swagger准确地展示API的输出模型，同时保留自定义HTTP状态码的能力。

深入理解Swagger与ResponseEntity的交互问题

在Spring Boot应用中，我们经常使用ResponseEntity来构建灵活的HTTP响应，它允许我们自定义状态码、头部信息和响应体。然而，当ResponseEntity与Swagger（或OpenAPI）结合使用时，如果不注意其类型定义，可能会导致API文档生成不准确。

考虑以下初始代码示例，它尝试根据用户权限返回激活码列表或未登录提示：

@ApiOperation(value = "show code")
@GetMapping("/showActivationCode")
@ApiResponses(
        {
                @ApiResponse(code = 200, message = "OK"),
                @ApiResponse(code = 403, message = "Not login"),
        })
public ResponseEntity showActivationCode() { // 注意这里ResponseEntity没有指定泛型类型
    if (session.getAttribute("isAdmin") == "1") {
        return ResponseEntity.status(200).body(userService.getActiveCode());
    } else {
        return ResponseEntity.status(403).body("Not login");
    }
}

其中userService.getActiveCode()返回List。当我们期望Swagger能展示ActiveCode对象的列表结构时，实际生成的Swagger文档却可能显示一个通用的ResponseEntity结构，例如：

{
  "body": {},
  "statusCode": "ACCEPTED",
  "statusCodeValue": 0
}

这种情况下，Swagger无法推断出body字段的具体类型，因为它接收的是一个原始（raw）的ResponseEntity类型。

为什么会出现这个问题？

Swagger在生成API文档时，会尝试通过反射等机制分析Java方法的返回类型。当方法返回ResponseEntity而没有指定泛型类型时，Java编译器将其视为ResponseEntity