如何让Swagger展示真实返回数据而非ResponseEntity结构？

问题场景 #

现有Spring Boot接口代码如下：

@ApiOperation(value = "show code")
@GetMapping("/showActivationCode")
@ApiResponses(
        {
                @ApiResponse(code = 200, message = "OK"),
                @ApiResponse(code = 403, message = "Not login"),
        })
public ResponseEntity showActivationCode() {
    if (session.getAttribute("isAdmin") == "1") {
        return ResponseEntity.status(200).body(userService.getActiveCode());
    } else {
        return ResponseEntity.status(403).body("Not login");
    }
}

服务层返回List<ActiveCode>：

public List<ActiveCode> getActiveCode() {
    return activeCodeDao.getActiveCodeListDao();
}

期望Swagger展示200状态码的返回结构为：

[
{
  "code": "string",
  "isAdmin": "string",
  "name": "string"
}
]

但当前Swagger展示的是ResponseEntity的默认结构，无法看到真实业务数据：

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

若将接口返回类型改为List<ActiveCode>，虽能正确展示结构，但无法自定义HTTP状态码，此方案不可行。

解决方案 #

方案一：为ResponseEntity指定泛型类型 #

将接口的返回类型从ResponseEntity改为ResponseEntity<List<ActiveCode>>，Swagger会自动识别泛型中的真实数据类型，同时不影响自定义HTTP状态码的功能。修改后的代码如下：

@ApiOperation(value = "show code")
@GetMapping("/showActivationCode")
@ApiResponses(
        {
                @ApiResponse(code = 200, message = "OK"),
                @ApiResponse(code = 403, message = "Not login"),
        })
public ResponseEntity<List<ActiveCode>> showActivationCode() {
    if ("1".equals(session.getAttribute("isAdmin"))) { // 注意：原代码用==比较字符串存在风险，建议改为equals
        return ResponseEntity.status(200).body(userService.getActiveCode());
    } else {
        return ResponseEntity.status(403).build();
    }
}

注意：原代码中session.getAttribute("isAdmin") == "1"存在字符串引用比较的风险，建议改为"1".equals(session.getAttribute("isAdmin"))避免空指针问题。

方案二：通过@ApiResponse指定返回类型 #

如果不想修改接口的返回类型泛型，可以在@ApiResponse注解中通过response和responseContainer属性明确指定返回数据类型：

@ApiOperation(value = "show code")
@GetMapping("/showActivationCode")
@ApiResponses(
        {
                @ApiResponse(code = 200, message = "OK", response = ActiveCode.class, responseContainer = "List"),
                @ApiResponse(code = 403, message = "Not login", response = String.class),
        })
public ResponseEntity showActivationCode() {
    if ("1".equals(session.getAttribute("isAdmin"))) {
        return ResponseEntity.status(200).body(userService.getActiveCode());
    } else {
        return ResponseEntity.status(403).body("Not login");
    }
}

• response = ActiveCode.class指定单个元素的类型
• responseContainer = "List"指定返回的是该类型的集合
• 403状态码指定response = String.class对应返回的字符串内容

这样Swagger就能正确展示各状态码对应的真实返回结构，同时保留自定义HTTP状态码的能力。

内容的提问来源于stack exchange，提问作者DoubleZeroWater