Open API 3 - add headers on individual content-type in responses

Question

I have my spec which have a path with a 200 response code, that response code can access multiple content-types, I want to add the Content-Disposition Header to one of those content-types.

Here's a sample:

openapi: '3.0.3'
info:
...
servers:
  ...
paths:          
  /examples:
    ...
    get:
      ...
      responses:
        '200':
          content:
            application/json:
              ...
            application/pdf:
              encoding:
                file:
                  headers:
                    Content-Disposition:
                      schema:
                        type: string
                        example: attachment; filename="name.pdf"
              examples:
                file:
                  summary: File
                  externalValue: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf

Here's the generated view:

no header

Here is an example where the header is added (for another endpoint)

responses:
  '201':
    description: Success
    headers:
      Location:
        schema:
          type: string
          format: uri
        description: The URI to the newly created example

And here's the generated view for that one:

with header

Am I doing something wrong?

Answer 1

encoding.<name>.headers is used to define headers for individual parts of a multipart/* request body, which is different from your scenario. Since your response is not multipart/*, the response headers must be defined in responses.<code>.headers.

However, OpenAPI does not have a way to vary response headers per media type. What you can do is define the Content-Disposition response header as optional and explain that it only applies to applicatioln/pdf responses.

paths:          
  /examples:
    get:
      responses:
        '200':
          description: ok
          content:
            application/pdf:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Used only with `application/pdf` responses.
              example: attachment; filename="name.pdf"