OpenAPI Generator未生成响应头信息的问题求助

我在使用OpenAPI Generator生成Spring接口代码时遇到了问题：OpenAPI规范中定义的响应头（myheader1和myheader2）没有被生成到@ApiResponse注解的headers参数中。即使按照建议升级了插件版本，问题依然存在。

OpenAPI规范片段 #

openapi: 3.0.3
...
  /foo:
    get:
      operationId: foo
      parameters:
        - name: bar
          in: query
          required: true
          schema:
            type: string
      responses:
        200:
          description: description
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
          headers:
            myheader1:
              description: myheader1 desc
              schema:
                type: string
            myheader2:
              description: myheader2 desc
              schema:
                type: integer
        401:
          description: "Unauthorized"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

生成的Spring接口代码（缺失响应头） #

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2024-01-24T14:16:01.056664+03:00[Europe/London]")
@Validated
@Tag(name = "Default", description = "the Default API")
@RequestMapping("${openapi.directoryServiceManager.base-path:/api/v1}")
public interface DefaultApi {

    /**
     * GET /foo
     *
     * @param bar  (required)
     * @return description (status code 200)
     *         or Unauthorized (status code 401)
     */
    @Operation(
        operationId = "foo",
        responses = {
            @ApiResponse(responseCode = "200", description = "description", content = {
                @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = String.class)))
            }),
            @ApiResponse(responseCode = "401", description = "Unauthorized", content = {
                @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorDto.class))
            })
        }
    )
    @RequestMapping(
        method = RequestMethod.GET,
        value = "/foo",
        produces = { "application/json" }
    )
    ResponseEntity<List<String>> foo(
        @NotNull 
@Parameter(name = "bar", description = "", required = true, in = ParameterIn.QUERY) @Valid @RequestParam(value = "bar", required = true) String bar
    );

}

初始环境配置 #

buildscript {
    dependencies {
        classpath("org.openapitools:openapi-generator-gradle-plugin:5.0.0")
    }
}

plugins {
    java
    kotlin("jvm")
    kotlin("plugin.spring") version "1.8.21"  
    id("org.springframework.boot") version "3.1.4"
    id("org.openapi.generator") version "6.3.0"
}

版本更新后的环境配置 #

buildscript {
    dependencies {
        classpath("org.openapitools:openapi-generator-gradle-plugin:7.2.0")
    }
}

plugins {
    java
    kotlin("jvm")
    kotlin("plugin.spring") version "1.8.21"
    id("io.spring.dependency-management") version "1.1.0"
    id("org.springframework.boot") version "3.1.4"
    id("org.openapi.generator") version "6.5.0"
    id("org.jlleitschuh.gradle.ktlint") version "11.5.0"
    jacoco
}

更新后生成的代码（仍无响应头） #

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2024-01-24T16:42:30.088851100+03:00[Europe/Moscow]")
@Validated
@Tag(name = "Default", description = "the Default API")
@RequestMapping("${openapi.directoryServiceManager.base-path:/api/v1}")
public interface DefaultApi {

    /**
     * GET /foo
     *
     * @param bar  (required)
     * @return description (status code 200)
     *         or Unauthorized (status code 401)
     */
    @Operation(
        operationId = "foo",
        responses = {
            @ApiResponse(responseCode = "200", description = "description", content = {
                @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = String.class)))
            }),
            @ApiResponse(responseCode = "401", description = "Unauthorized", content = {
                @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorDto.class))
            })
        }
    )
    @RequestMapping(
        method = RequestMethod.GET,
        value = "/foo",
        produces = { "application/json" }
    )
    
    ResponseEntity<List<String>> foo(
        @NotNull 
@Parameter(name = "bar", description = "", required = true, in = ParameterIn.QUERY) @Valid @RequestParam(value = "bar", required = true) String bar
    );

}

解决办法 #

1. 启用响应头生成配置
   OpenAPI Generator的Spring代码生成器默认不会生成响应头信息，需要在gradle的openApiGenerate任务中显式添加useResponseHeaders配置项：

   openApiGenerate {
       generatorName = "spring"
       inputSpec = "$projectDir/src/main/resources/your-openapi-spec.yaml".toString()
       outputDir = "$buildDir/generated".toString()
       apiPackage = "com.yourpackage.api"
       modelPackage = "com.yourpackage.model"
       configOptions = [
           useResponseHeaders: "true",
           // 其他必要配置
       ]
   }
   

   该配置会触发代码生成器将OpenAPI规范中的响应头转换为@ApiResponse注解的headers参数。

2. 确保插件版本匹配
   保证org.openapi.generator插件版本和openapi-generator-gradle-plugin版本一致（建议都使用7.2.0及以上版本），避免版本不兼容导致配置失效。

3. 检查自定义模板（如果有）
   如果你自定义了Spring代码生成的模板文件，需要确认模板中包含响应头的生成逻辑。比如在api.mustache模板中，需要添加处理响应头的代码段，确保@ApiResponse注解中包含headers参数。

配置生效后，生成的@ApiResponse注解会包含响应头信息，示例如下：

@ApiResponse(responseCode = "200", description = "description", 
    content = {
        @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = String.class)))
    },
    headers = {
        @Header(name = "myheader1", description = "myheader1 desc", schema = @Schema(type = "string")),
        @Header(name = "myheader2", description = "myheader2 desc", schema = @Schema(type = "integer"))
    }
)

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