OpenAPI 3.1如何在Swagger UI/Redoc中添加PDF响应示例下载链接？

问题分析 #

你的配置核心逻辑没问题，但可能因为路径指向、UI兼容细节导致无法生成下载链接，以下是修正后的配置和关键注意事项：

正确JSON配置示例 #

"/myapplication/pdfresponse": {
  "get": {
    "responses": {
      "200": {
        "description": "PDF格式响应.",
        "content": {
          "application/pdf": {
            "schema": {
              "type": "string",
              "format": "binary"
            },
            "examples": {
              "exampleName": {
                "summary": "PDF格式示例",
                "externalValue": "./examples/abc.pdf"
              }
            }
          }
        },
        "headers": {
          "Content-Disposition": {
            "schema": {
              "type": "string",
              "default": "attachment; filename=abc.pdf"
            }
          }
        }
      }
    }
  }
}

关键调整与注意事项 #

• 路径明确性：将externalValue改为./examples/abc.pdf，确保相对路径基于OpenAPI规范文件的位置（比如规范在根目录，PDF在同级examples文件夹下）。如果是线上部署，要确保PDF文件放在UI服务器能访问到的静态资源目录，路径改为对应的绝对URL。
• Header优化：把example替换为default，让UI更明确地识别这是响应头的默认值，帮助生成下载逻辑。
• Swagger UI本地调试：如果用本地Swagger UI打开规范文件，需要在浏览器启动时添加--allow-file-access-from-files参数（Chrome），否则浏览器会阻止访问本地文件。
• Redoc兼容处理：如果使用Redoc，需要给示例添加x-redoc扩展强制开启下载选项：

  "examples": {
    "exampleName": {
      "summary": "PDF格式示例",
      "externalValue": "./examples/abc.pdf",
      "x-redoc": {
        "download": true
      }
    }
  }
  

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