Describing a GET request returning a file in OpenAPI 3.0

Question

I am writing an OpenAPI 3.0 specification and have an endpoint returning a file. Now I found documentation on the website of Swagger but that's about a POST request: https://swagger.io/docs/specification/describing-request-body/multipart-requests/.

There's also another StackOverflow question with zero responses about my question, so I will give it another go.

How does one write a specification for a GET request where a file should be returned?

I currently have the following:

      responses:
        '200':
          description: ok
          content:
            multipart/form-data:
              schema:
                type: object
                description: The multipart object containing the file bytes
                properties:
                  file:
                    type: string
                    format: binary
                    description: Bytes of the file

But I think this is mostly for POST request, to upload a file. Does anyone know what it should be?

What kind of file does your endpoint return - text, PDF, ZIP, audio, arbitrary binary file, ...? — Helen, Oct 24 '22 at 09:17

score 1 · Answer 1 · answered Oct 25 '22 at 07:51

1

In OpenAPI 3.0, a response containing a PDF, PNG, or JPG file is described as follows:

      responses:
        '200':
          description: A PDF file, PNG image, or JPG image
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:  # 'jpeg' not 'jpg', see https://stackoverflow.com/q/33692835
              schema:
                type: string
                format: binary

answered Oct 25 '22 at 07:51

Helen

87,344
17
243
314

What about `MP4` file? – Eli Zatlawy Mar 28 '23 at 13:21
@none MP4 is also `type: string` + `format: binary`. Just use the correct media type (e.g. [video/mp4](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter)) under the `content` key. – Helen Mar 28 '23 at 15:15
I tried it, but I still get `Unrecognized response type; displaying content as text.` – Eli Zatlawy Mar 29 '23 at 07:01
Make sure your server response has the correct `Content-Type` header, e.g. `Content-Type: video/mp4`. – Helen Mar 29 '23 at 12:15
Yes, it has, it works fin from `Postman` for example. – Eli Zatlawy Mar 30 '23 at 07:41

Describing a GET request returning a file in OpenAPI 3.0

1 Answers1