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

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"