如何用@ApiResponse标注转发第三方HTTP请求的各类响应信息

1. 完整标注第三方所有错误响应码与结构 #

直接在@ApiResponses中追加第三方接口可能返回的所有错误响应条目，每个条目用@ApiResponse指定对应的响应码、说明文本，以及第三方接口返回的错误DTO类。同时要在说明里明确标注该响应是直接转发自第三方接口。

2. 补充全局说明 #

可以在@ApiOperation的notes字段里，或者新增一个通用的@ApiResponse（比如用code = "default"）来统一说明：当请求失败时，本接口不会生成自有错误响应结构，而是直接透传第三方接口返回的所有响应内容（包括响应码、响应体）。

代码示例 #

假设第三方接口可能返回400（参数错误）、401（未授权）、403（权限不足）、500（服务异常）这几种错误，对应的错误DTO分别是BadRequestDTO、UnauthorizedDTO、ForbiddenDTO、ThirdPartyErrorDTO，完整的注解写法如下：

@ApiOperation(
    value = "调用第三方接口执行重启操作",
    notes = "成功时返回自定义SuccessDTO；请求失败时，将直接转发第三方接口返回的所有响应（包括响应码、响应体），不生成自有错误结构"
)
@ApiResponses(value = {
        // 成功响应
        @ApiResponse(code = 200, message = "操作成功", response = SuccessDTO.class),
        // 第三方接口可能返回的错误响应
        @ApiResponse(code = 400, message = "参数错误（转发自第三方接口）", response = BadRequestDTO.class),
        @ApiResponse(code = 401, message = "未授权（转发自第三方接口）", response = UnauthorizedDTO.class),
        @ApiResponse(code = 403, message = "权限不足（转发自第三方接口）", response = ForbiddenDTO.class),
        @ApiResponse(code = 500, message = "第三方服务异常（转发自第三方接口）", response = ThirdPartyErrorDTO.class),
        // 兜底说明所有未明确列出的第三方响应
        @ApiResponse(code = "default", message = "其他错误（直接转发自第三方接口的响应内容）")
})
@GetMapping("/restart")
public ResponseEntity<SuccessDTO> restart() {
    URI uriRestartNO = // 构造第三方接口URI
    return restTemplate.getForEntity(uriRestartNO.toUri(), SuccessDTO.class);
}

关键说明 #

• 每个错误响应的message字段要明确标注「转发自第三方接口」，让调用方清楚响应来源
• 如果第三方接口的错误响应结构不统一，可以用response = Object.class或者通用的第三方错误父类来覆盖
• code = "default"的条目可以兜底覆盖所有未明确列出的第三方响应，避免遗漏

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