如何在Swagger生成的REST API中针对不同响应码返回不同对象

Swagger 2.0官方提供的Spring代码生成模板，默认会取接口200响应的Schema作为方法返回值的泛型约束，因此生成的接口固定返回ResponseEntity<ExampleResponse>，导致返回其他状态码对应的响应对象时出现类型不匹配的编译错误。

• 调整Codegen配置放宽返回类型约束
  可以在Swagger Codegen的执行配置中添加参数，将接口返回值的泛型设置为无约束通配符。比如使用Maven插件执行代码生成时，在配置项中添加<returnGenericResponse>true</returnGenericResponse>，生成的方法返回类型会变为ResponseEntity<?>，此时无论返回成功还是失败类型的对象都可以正常编译。且接口上的@ApiResponses注解已经声明了不同状态码对应的响应结构，不会影响接口文档的展示正确性。

• 自定义异常+全局异常处理方案（更推荐）
  这是业界普遍使用的规范实现方式，完全不需要修改自动生成的接口代码，逻辑不会被后续重新执行Codegen的操作覆盖。
  实现步骤：

1. 自定义业务异常类，内部封装错误响应对象的相关属性
2. 编写全局异常处理器，用@RestControllerAdvice注解标注，捕获对应自定义异常后转换为错误响应对象，包装为对应状态码的ResponseEntity返回
3. 业务实现代码中，正常流程直接返回200状态对应的响应对象，遇到错误场景直接抛出对应自定义异常即可

代码示例：
自定义异常类：

public class BadRequestBizException extends RuntimeException {
    private final ExampleError error;
    public BadRequestBizException(String errorCode) {
        this.error = new ExampleError();
        this.error.setCode(errorCode);
    }
    public ExampleError getError() {
        return error;
    }
}

全局异常处理器：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(BadRequestBizException.class)
    public ResponseEntity<ExampleError> handleBadRequestException(BadRequestBizException e) {
        return new ResponseEntity<>(e.getError(), HttpStatus.BAD_REQUEST);
    }
}

委托类实现：

@Override
public ResponseEntity<ExampleResponse> exampleCall() {
    // 错误场景直接抛异常
    if (/* 业务校验不通过逻辑 */) {
        throw new BadRequestBizException("123");
    }
    // 正常场景返回成功响应
    ExampleResponse resp = new ExampleResponse();
    resp.setResult("操作成功");
    return ResponseEntity.ok(resp);
}

• 升级到OpenAPI 3.x规范
  如果可以调整接口定义版本，OpenAPI 3.x提供了oneOf关键字可明确声明多响应类型，新版的OpenAPI Generator可以更好的支持多响应类型的代码生成，不过需要将原有Swagger 2.0的定义调整为OpenAPI 3.x格式。

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