Flask中send_file返回tar文件时Swagger下载文件名异常如何解决？

问题根因 #

Swagger UI 对文件下载响应的解析逻辑和 Postman 不同：Postman 会优先识别响应头中 Content-Disposition 的 filename 字段，而 Swagger UI 触发随机文件名通常有两个原因：

1. 跨域场景下未显式暴露 Content-Disposition 响应头，Swagger UI 无权限读取该字段，只能自动生成随机文件名
2. 自动生成的 Content-Disposition 头格式不符合 Swagger UI 的解析规则

修复步骤 #

1. 调整后端响应逻辑 #

显式规范设置响应头，跨域场景下额外添加头暴露配置（以你使用的Flask框架为例）：

from flask import send_file
# 如使用flask-cors处理跨域，添加暴露Content-Disposition头的配置
from flask_cors import CORS
CORS(app, expose_headers=["Content-Disposition"])

# 接口逻辑调整
response = send_file(
    fpath, 
    as_attachment=True, 
    mimetype="application/octet-stream",
    download_name="migration.tar"
)
# 手动指定Content-Disposition头，确保格式符合Swagger解析要求
response.headers["Content-Disposition"] = "attachment; filename=migration.tar"
return response

注意：如果你的 Flask 版本低于 2.0，send_file 的文件名参数需替换为 attachment_filename 而非 download_name，避免参数失效。

2. 校验Swagger接口定义 #

确保该接口的OpenAPI配置正确声明了二进制返回类型：

• 200响应的content类型设置为 application/octet-stream
• 响应结构声明为：type: string, format: binary

验证方式 #

修改完成后先通过浏览器开发者工具的网络面板，查看接口响应头是否正常返回 Content-Disposition: attachment; filename=migration.tar，确认头存在后再在Swagger UI测试即可。

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