开放 API 3 - 在响应中的单个内容类型上添加标头

Question

我的规范有一个带有 200 响应代码的路径，该响应代码可以访问多个内容类型，我想将 Content-Disposition 标头添加到这些内容类型之一。

这是一个示例：

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

这是生成的视图：

无标题

这是添加标头的示例（对于另一个端点）

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

这是生成的视图：

带标题

难道我做错了什么？

Answer 1

encoding.<name>.headers用于为multipart/* 请求正文的各个部分定义标头，这与您的场景不同。由于您的响应不是multipart/*，因此响应标头必须在 中定义responses.<code>.headers。

但是，OpenAPI 无法根据媒体类型改变响应标头。您可以做的是将Content-Disposition响应标头定义为可选，并解释它仅适用于applicatioln/pdf响应。

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"