Swagger中无法下载Content-Type为application/pdf的PDF文件

问题分析 #

你遇到的情况是：Express接口返回PDF文件在Postman中正常，但Swagger UI会把二进制内容当成文本显示，报错Unrecognized response type; displaying content as text.；改成application/octet-stream虽能触发下载，但需要手动加后缀。核心问题是Swagger UI对application/pdf类型的响应处理需要更明确的配置，才能识别这是一个带文件名的附件下载。

解决方案 #

1. 保持Express端的响应头配置不变 #

继续使用正确的PDF类型和带文件名的Content-Disposition，可额外增加传输编码声明增强兼容性：

res.setHeader('Content-Type', 'application/pdf');
res.setHeader('Content-Disposition', 'attachment; filename=download.pdf');
// 可选：明确二进制传输的声明
res.setHeader('Content-Transfer-Encoding', 'binary');
res.send(pdfBuffer); // 替换为你的PDF Buffer数据

2. 调整Swagger的响应配置，明确声明响应头和文件类型 #

修改Swagger响应配置，增加headers字段明确指定Content-Disposition，让Swagger UI识别这是带文件名的附件：

"responses": {
  "200": {
    "description": "返回PDF格式的下载文件",
    "headers": {
      "Content-Disposition": {
        "description": "指定下载文件的名称",
        "schema": {
          "type": "string",
          "example": "attachment; filename=download.pdf"
        }
      }
    },
    "content": {
      "application/pdf": {
        "schema": {
          "type": "string",
          "format": "binary"
        }
      }
    }
  }
}

3. 旧版Swagger UI兼容方案 #

如果你的Swagger UI版本较低（如v2.x），对application/pdf支持不足，可在content中同时添加application/octet-stream作为备选，既保留正确的PDF类型声明，又能触发下载按钮：

"content": {
  "application/pdf": {
    "schema": {
      "type": "string",
      "format": "binary"
    }
  },
  "application/octet-stream": {
    "schema": {
      "type": "string",
      "format": "binary"
    }
  }
}

这样配置后，Swagger UI会识别到这是需要下载的二进制文件，同时自动使用download.pdf作为文件名，无需手动添加后缀。

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