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

你离开我真会死。 提交于 2021-01-03 06:52:24

问题


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?


回答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"


来源:https://stackoverflow.com/questions/62739261/open-api-3-add-headers-on-individual-content-type-in-responses

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!