打开 API 3 - 在回复中对个人 content-type 添加 headers

Question

我的规范有一个带有 200 响应代码的路径，该响应代码可以访问多个 content-types，我想将 Content-Disposition Header 添加到其中一个content-types.

这是一个示例：

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

这是生成的视图：

no header

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

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

下面是为该视图生成的视图：

with header

我是不是做错了什么？

Answer 1

encoding.<name>.headers用于为multipart/*请求body的各个部分定义header，这是不同的从你的场景。由于您的响应不是 multipart/*，响应 header 必须在 responses.<code>.headers 中定义。

但是，OpenAPI 无法改变每种媒体类型的响应 headers。您可以做的是将 Content-Disposition 响应 header 定义为可选，并说明它仅适用于 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"

打开 API 3 - 在回复中对个人 content-type 添加 headers

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

openapi

swagger-editor