OpenAPI-提供下载 pdf 格式响应示例的链接（添加 pdf 示例）

Question

在 Openapi 中，需要在 Swagger UI/Redoc 等中提供 pdf 格式的响应示例作为下载链接。

我正在使用 OpenAPI 3.1 和 API 之一。我需要将响应示例显示为 pdf 文件，该文件基于外部示例托管（本地）。它可能是在 UI 中下载 PDF 的链接。在尝试了各种方法后，我无法在 Swagger UI 和 Redoc UI 中获取下载文件的链接。

我正在使用基于 JSON 的 OpenAPI。我已经提到了开放 API 3 - 在响应中的单个内容类型上添加标头并以 JSON 实现它。但就我而言，我无法使其发挥作用。

样品如下：

"/myapplication/pdfresponse": { 
"get": { 
    "responses": { 
        "200": { 
                "description": "PDF format response.",      
                "content": {
                  "application/pdf": {
                  "schema":{
                    "type": "string",
                    "format":"binary"
                    },
                  "examples":{ 
                    "exampleName":{
                        "summary":"PDF format.",
                        "externalValue": "examples/abc.pdf"
                    } 
                   }
                  } 
                },
                "headers":{
                  "Content-Disposition":{
                    "schema":{
                      "type": "string",
                      "example": "attachment; filename=abc.pdf"               
                      } 
                    } 
                  }          
               }
              }

可能标头内容配置错误或需要其他内容。请提供 JSON 示例，或者如果我遗漏了什么，请告诉我。谢谢...！

Answer 1

我认为你要求的是提供pdf文档的下载网址。

您需要使用

externalValue

并提供 作为下载位置的

uri

除非您将文件托管在本地以外的其他位置，否则这可能不起作用。我有一种感觉，cors 会在 ui 的本地实例上阻止此请求。

我知道在撰写本文时，Redoc 无法解决

externalValue

uris。如果您想发表评论、贡献或以其他方式了解最新进展，可以关注此问题。

{
    "openapi": "3.1.0",
    "info": {
        "title": "test api",
        "version": "1.0.0"
    },
    "paths": {
        "/api/v1/thing": {
            "get": {
                "responses": {
                    "200": {
                        "description": "thing",
                        "content": {
                            "application/pdf": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                },
                                "examples": {
                                    "pdf_example": {
                                        "summary": "a download link for a pdf",
                                        "externalValue": "file://C:\\Users\/<user>\/Downloads\/1testing.pdf"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}