Spring Boot3中OpenApi生成接口返回类型为Object的问题排查

我定义了一个用户注册API，期望用户注册成功后返回SaveUserResponse。但执行Gradle构建后生成的接口中，signup方法的返回类型为ResponseEntity<Object>，而非预期的ResponseEntity<SaveUserResponse>。

我的userapi.yaml配置： #

paths:
  /signup:
    post:
      description: User registration API
      operationId: signup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'

      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                $ref: '#components/schemas/SaveUserResponse'


components:
  schemas:
    SignupRequest:
      type: object
      description: User model for GetARoom
      required:
        - firstName
        - lastName
        - email
        - password
      properties:
        firstName:
          type: string
          description: First name of the user
          minLength: 2
          maxLength: 15

        lastName:
          type: string
          description: Last name of the user
          minLength: 1
          maxLength: 15

        email:
          type: string
          description: User's email address.

        password:
          type: string
          format: password
          description: Password of the user
          pattern: /^(?=.*[0-9])(?=.*[a-z]).{8,12}$/
          minLength: 8
          maxLength: 12
    
    SaveUserResponse:
      type: object
      properties:
        accountNumber:
          type: integer
        userId:
          type: string

我的build.gradle配置： #

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'org.openapi.generator' version '6.6.0'
}

group = 'com.ums'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

sourceSets {
    main {
        java {
            srcDirs("$buildDir/generated/openapi/src/main/java")
        }
    }
}

openApiGenerate {
    generatorName = "spring"
    inputSpec.set("$projectDir/src/main/resources/api/userapi.yaml")
    outputDir.set("$buildDir/generated/openapi")
    apiPackage.set("com.ums.userservice.api")
    modelPackage.set("com.ums.userservice.model")
    configOptions = [
            library : "spring-boot",
            useSpringBoot3: "true"
    ]

    additionalProperties = [
            dateLibrary: "java8",
            generateModels: true,
            generateApis: true,
            interfaceOnly: true,
            skipDefaultInterface: true,
            useBeanValidation: true,
            serializableModel: true
    ]
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation group: 'org.openapitools', name: 'jackson-databind-nullable', version: '0.2.6'


    implementation group: 'io.swagger.core.v3', name: 'swagger-annotations', version: '2.2.21'
    implementation group: 'io.swagger', name: 'swagger-annotations', version: '1.6.14'

    compileOnly group: 'org.projectlombok', name: 'lombok', version: '1.18.24'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    annotationProcessor 'org.projectlombok:lombok:1.18.24'

    testCompileOnly 'org.projectlombok:lombok:1.18.24'
    testAnnotationProcessor 'org.projectlombok:lombok:1.18.24'
}

tasks.named('test') {
    useJUnitPlatform()
}

tasks.withType(JavaCompile) {
    dependsOn(tasks.openApiGenerate)
}

请问我遗漏了哪些配置？

问题出在两个地方，调整后即可解决：

1. 修复OpenAPI YAML的引用语法错误
   你在响应中引用SaveUserResponse时用了#components/schemas/SaveUserResponse，正确的OpenAPI引用格式必须以#/开头，也就是#/components/schemas/SaveUserResponse。这个语法错误会导致代码生成器无法识别指定的响应模型，只能 fallback 到Object类型。

   修改后的响应部分代码：

   responses:
     '201':
       description: CREATED
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/SaveUserResponse'
   

2. 在Gradle配置中添加useResponseEntity参数
   在openApiGenerate的additionalProperties里添加useResponseEntity: "true"，明确告诉代码生成器使用ResponseEntity来封装响应类型，而不是默认的Object。

   修改后的additionalProperties配置：

   additionalProperties = [
           dateLibrary: "java8",
           generateModels: true,
           generateApis: true,
           interfaceOnly: true,
           skipDefaultInterface: true,
           useBeanValidation: true,
           serializableModel: true,
           useResponseEntity: "true"
   ]
   

完成以上两处修改后，重新执行Gradle构建，生成的signup方法返回类型就会变成ResponseEntity<SaveUserResponse>。

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