开放 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"