OpenAPI Generator生成Spring接口无法添加Content-Disposition响应头

是否Spring生成器不支持响应头配置？ #

是的，旧版本（v5及之前）的OpenAPI Generator Spring代码生成器，对响应头的自动生成支持不完善——不会把你在OpenAPI规范里定义的content-disposition头自动添加到生成的控制器逻辑中，Swagger UI也因为生成的代码里没包含头的元数据，所以不会显示这个响应头。不过新版本（v6+）的生成器已经修复了这个问题，对响应头的支持更完善。

替代方案 #

针对你的情况，这里提供几个适合新手的解决方法：

1. 手动在控制器实现类中添加响应头

找到生成的控制器实现类（比如FileApiImpl），修改getFile方法，通过ResponseEntity或者HttpServletResponse来设置响应头：

• 用ResponseEntity的方式（推荐）：

  import org.springframework.http.HttpHeaders;
  import org.springframework.http.ResponseEntity;
  import java.io.File;
  import org.springframework.core.io.FileSystemResource;
  
  @Override
  public ResponseEntity<FileSystemResource> getFile() {
      // 假设你已经获取到要下载的文件对象
      File file = new File("/path/to/keyFile.pem");
      FileSystemResource resource = new FileSystemResource(file);
  
      return ResponseEntity.ok()
          .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=keyFile.pem")
          .body(resource);
  }
  

• 用HttpServletResponse的方式：

  import javax.servlet.http.HttpServletResponse;
  import org.springframework.http.HttpHeaders;
  import java.nio.file.Files;
  
  @Override
  public void getFile(HttpServletResponse response) throws IOException {
      // 写入文件内容到response的输出流
      File file = new File("/path/to/keyFile.pem");
      response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=keyFile.pem");
      response.setContentType("application/octet-stream");
      // 复制文件内容到response输出流
      Files.copy(file.toPath(), response.getOutputStream());
      response.getOutputStream().flush();
  }
  

2. 让Swagger UI显示响应头

如果需要Swagger UI展示这个响应头，手动在生成的控制器接口（比如FileApi）的getFile方法上添加@ApiResponse注解：

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.headers.ApiHeader;
import io.swagger.v3.oas.annotations.Operation;

@Operation(summary = "Returns the file", operationId = "getFile")
@ApiResponse(responseCode = "200", description = "A file", headers = {
    @ApiHeader(name = "content-disposition", description = "Content disposition header", example = "attachment; filename=keyFile.pem")
})
ResponseEntity<FileSystemResource> getFile();

3. 升级OpenAPI Generator版本

如果不想手动修改代码，建议升级到v6及以上的OpenAPI Generator稳定版，新版本会根据你在OpenAPI规范里定义的响应头，自动生成对应的代码逻辑和Swagger元数据，重新生成代码后应该就能正常显示和生效。

4. 自定义代码生成模板（进阶）

如果需要长期维护，不想每次生成代码后手动修改，可以自定义OpenAPI Generator的Mustache模板（比如api.mustache或apiImpl.mustache），在模板中添加响应头的处理逻辑。不过这个需要你了解模板语法，适合有一定基础后尝试。

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