解决Java Excel接口通过OpenAPI下载的文件格式错误问题

我有一个可创建Excel文件并写入输出流的Java接口，想用OpenAPI下载该Excel文件验证构造是否正确，但遇到异常：OpenAPI下载的是txt文件，修改后缀为xlsx后打开提示文件格式错误。

Java接口代码片段 #

@ApiResponses(value = {
        @ApiResponse(responseCode = "200", content = @Content(mediaType = "application/vnd.ms-excel"))
})
@PostMapping(value = "/download-excel")
@ResponseStatus(HttpStatus.OK)
public void getExcelForIds(
        @RequestBody List<Long> ids,
        HttpServletResponse response
) throws IOException {
    response.setContentType("application/vnd.ms-excel");
    response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "inline;filename=\"myfilename.xlsx\"");
    excelWriter.writeIdsToExcel(ids, response.getOutputStream());
}

OpenAPI响应截图 #

问题分析与修复方案 #

1. 修正媒体类型 #

xlsx格式对应的标准媒体类型是application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，你当前使用的application/vnd.ms-excel是旧版xls格式的类型，这会导致OpenAPI无法正确识别文件类型，默认按txt处理。

2. 调整Content-Disposition头 #

• 将inline改为attachment，明确告知浏览器这是需要下载的附件，避免渲染异常
• 添加UTF-8编码的文件名参数，提升浏览器兼容性
  修改后的头配置：

response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment;filename=\"myfilename.xlsx\";filename*=UTF-8''myfilename.xlsx");

3. 同步更新OpenAPI注解 #

更新@ApiResponse中的mediaType，确保接口文档与实际响应的媒体类型一致，让OpenAPI能正确识别文件类型：

@ApiResponse(responseCode = "200", content = @Content(mediaType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"))

4. 完善输出流处理 #

写入完成后刷新并关闭输出流，避免数据不完整导致文件损坏：

response.getOutputStream().flush();
response.getOutputStream().close();

5. 验证Excel生成逻辑 #

确认excelWriter.writeIdsToExcel方法生成的是标准xlsx格式文件，而非xls或其他非标准格式，这是文件无法打开的核心原因之一。

修正后的完整代码示例 #

@ApiResponses(value = {
        @ApiResponse(responseCode = "200", content = @Content(mediaType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"))
})
@PostMapping(value = "/download-excel")
@ResponseStatus(HttpStatus.OK)
public void getExcelForIds(
        @RequestBody List<Long> ids,
        HttpServletResponse response
) throws IOException {
    response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
    response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment;filename=\"myfilename.xlsx\";filename*=UTF-8''myfilename.xlsx");
    excelWriter.writeIdsToExcel(ids, response.getOutputStream());
    response.getOutputStream().flush();
    response.getOutputStream().close();
}

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