OpenAPI Generator Spring：多成功状态码泛型返回类型配置疑问

解决方案 #

1. 在OpenAPI规范中定义通用父响应类 #

先在components/schemas里定义一个抽象的通用响应类，让200和202的响应Schema都继承这个父类，生成器会自动使用父类作为返回类型：

components:
  schemas:
    BaseResponse:
      type: object
      properties:
        data:
          type: array
          items: {} # 定义抽象的数组项，兼容任意类型
    ModelA:
      # 原ModelA的Schema定义
    ModelB:
      # 原ModelB的Schema定义
    Model200Response:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/ModelA"
    Model202Response:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/ModelB"

修改后的responses部分引用这两个子类：

responses:
  "200":
    description: Http status 200 response
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Model200Response"
  "202":
    description: Http status 202 response
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Model202Response"

生成的接口返回类型会变为ResponseEntity<BaseResponse>，兼容两种响应结构。

2. 使用OpenAPI Generator的内置配置参数 #

添加以下配置到生成器的配置文件（如generator-config.yaml）：

configOptions:
  returnResponse: true
  useGenericResponse: true

或者在命令行生成时直接指定参数：

openapi-generator generate -g spring -i your-spec.yaml -o output-dir --config generator-config.yaml

useGenericResponse参数会强制生成器使用ResponseEntity<Object>作为接口返回类型，覆盖默认的具体Model类型。注意该参数在Spring 6.x版本的生成器中已支持，需要确认版本兼容性。

3. 自定义代码模板 #

如果以上方法无法满足需求，可以修改Spring生成器的接口模板：

1. 找到Spring生成器的默认模板文件api.mustache
2. 修改模板中返回类型的逻辑，将硬编码的具体Model替换为Object或自定义抽象类：

   default ResponseEntity<{{#returnType}}{{{returnType}}}{{/returnType}}{{^returnType}}Object{{/returnType}}> {{operationId}}(...)
   

3. 生成代码时指定自定义模板路径：

   openapi-generator generate -g spring -i your-spec.yaml -o output-dir -t /path/to/your/custom-templates
   

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