OpenAPI- Provide a link to download response's examples in pdf (adding examples for pdf)

Question

In Openapi, response's example which is in pdf need to be provided as download link in Swagger UI/Redoc etc.

I am using OpenAPI 3.1 and for one of API. I need to show example of response as pdf file which is hosted(locally) based on External Examples. It could be a link for downloading PDF in UIs. After trying various methods I am unable to get link to download file in Swagger UI as well as in Redoc UI.

I am using JSON based OpenAPI. I have referred Open API 3 - add headers on individual content-type in responses and implement it in JSON. But in my case i am unable to make it work.

Sample is as follows:

"/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"               
                      } 
                    } 
                  }          
               }
              }

Probably headers content-disposition is wrong or something else is required. Please provide sample of JSON or let me know if I am missing something. Thanks...!

Answer 1

I think what you're asking is to provide a download url of the pdf document.

You need to use externalValue and provide the <string> as a uri of the download location

This probably won't work unless you host the file somewhere else other than local. I have a feeling cors will block this request on a local instance of the ui.

I know as of writing, Redoc does not resolve externalValue uris. You can follow this issue if you want to comment, contribute or otherwise stay up to date on the progress of it.

{
    "openapi": "3.1.0",
    "info": {
        "title": "test api",
        "version": "1.0.0"
    },
    "paths": {
        "/api/v1/thing": {
            "get": {
                "responses": {
                    "200": {
                        "description": "thing",
                        "headers": {
                            "content-disposition": {
                                "schema": {
                                    "type": "string"
                                },
                                "examples": {
                                    "sample_header": {
                                        "value": "application/pdf; attachment; filename: sample.pdf"
                                    }
                                }
                            }
                        },
                        "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"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}