如何让OpenAPI Generator生成ResponseEntity<?>而非ResponseEntity<SuccessMessage>

我使用OpenAPI Generator Maven插件（7.0.0-beta版）生成Spring Boot代码，根据指定的OpenAPI 3.0.3规格，createOrder接口当前生成的返回类型是ResponseEntity<SuccessMessage>，但希望改成ResponseEntity<?>。已知可通过修改Mustache模板实现，想了解其他解决方案。

相关资源 #

原OpenAPI规格

openapi: 3.0.3
info:
  title: My App
  version: 1.0.0
tags:
  - name: Order
    description: "Order endpoints"
paths:
  /api/v0/order:
    post:
      tags:
        - Order
      summary: 'Create Order'
      operationId: createOrder
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Order'
        required: true
      responses:
        200:
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/SuccessMessage'
        400:
          description: Error
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Order:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
    SuccessMessage:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
        message:
          type: array
          items:
            type: string

当前生成的代码片段

@Operation(
    operationId = "createOrder",
    summary = "Create Order",
    tags = { "Order" },
    responses = {
        @ApiResponse(responseCode = "200", description = "OK", content = {
            @Content(mediaType = "application/json", schema = @Schema(implementation = SuccessMessage.class))
        }),
        @ApiResponse(responseCode = "400", description = "Error", content = {
            @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorMessage.class))
        })
    }
)
@RequestMapping(
    method = RequestMethod.POST,
    value = "/api/v0/order",
    produces = { "application/json" },
    consumes = { "application/json" }
)
default ResponseEntity<SuccessMessage> createOrder(
    @Parameter(name = "Order", description = "", required = true) @Valid @RequestBody Order order
) {
    return getDelegate().createOrder(order);
}

期望的返回类型

default ResponseEntity<?> createOrder

原Maven插件配置

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.0.0-beta</version>
    <configuration>
        <generateModelTests>false</generateModelTests>
        <generateApiTests>false</generateApiTests>
        <configOptions>
            <dateLibrary>java8</dateLibrary>
            <serializableModel>true</serializableModel>
            <openApiNullable>false</openApiNullable>
        </configOptions>
    </configuration>
    <executions>
        <execution>
            <id>catalog_api</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/specs/order_api_v1.yml</inputSpec>
                <generatorName>spring</generatorName>
                <library>spring-boot</library>
                <apiPackage>com.order.api</apiPackage>
                <modelPackage>com.order.model</modelPackage>
                <supportingFilesToGenerate>
                    ApiUtil.java
                </supportingFilesToGenerate>
                <configOptions>
                    <useTags>true</useTags>
                    <useBeanValidation>true</useBeanValidation>
                    <returnSuccessCode>true</returnSuccessCode>
                    <delegatePattern>true</delegatePattern>
                    <implicitHeaders>true</implicitHeaders>
                    <useSpringBoot3>true</useSpringBoot3>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

可选解决方案 #

方案1：修改OpenAPI规格，定义通用响应类型 #

在OpenAPI规格中用oneOf统一响应的schema类型，让生成器识别到接口可能返回多种类型，从而生成泛型为通配符的返回值。

修改后的响应配置示例

responses:
  200:
    description: OK
    content:
      'application/json':
        schema:
          oneOf:
            - $ref: '#/components/schemas/SuccessMessage'
            - $ref: '#/components/schemas/ErrorMessage'
  400:
    description: Error
    content:
      'application/json':
        schema:
          oneOf:
            - $ref: '#/components/schemas/SuccessMessage'
            - $ref: '#/components/schemas/ErrorMessage'

或者先定义一个通用响应schema，再引用：

components:
  schemas:
    GeneralResponse:
      oneOf:
        - $ref: '#/components/schemas/SuccessMessage'
        - $ref: '#/components/schemas/ErrorMessage'

然后在响应中替换为$ref: '#/components/schemas/GeneralResponse'，生成的返回类型会是ResponseEntity<GeneralResponse>，如果需要严格的ResponseEntity<?>，可以结合下面的配置参数。

方案2：添加Maven插件配置参数 #

在插件的configOptions中加入<returnResponse>true</returnResponse>，这个参数会让生成的接口返回不带泛型的ResponseEntity，和ResponseEntity<?>完全兼容，代码修改如下：

<configOptions>
    <useTags>true</useTags>
    <useBeanValidation>true</useBeanValidation>
    <returnSuccessCode>true</returnSuccessCode>
    <delegatePattern>true</delegatePattern>
    <implicitHeaders>true</implicitHeaders>
    <useSpringBoot3>true</useSpringBoot3>
    <!-- 新增配置 -->
    <returnResponse>true</returnResponse>
</configOptions>

方案3：自定义代码生成扩展 #

如果上述方案都不满足，可以编写自定义扩展类修改Spring生成器的返回类型逻辑，但这种方式复杂度较高，适合需要大量定制化的场景。

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