Open API 3 - 在响应中的单个内容类型上添加标头 [英] Open API 3 - add headers on individual content-type in responses

问题描述

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

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.

这是一个示例:

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 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:

带标题

我做错了什么吗?

推荐答案

encoding..headers 用于为 multipart/* 的各个部分定义标题code> request body，这与您的场景不同.由于您的响应不是 multipart/*，因此必须在 responses..headers.

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.

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

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"

这篇关于Open API 3 - 在响应中的单个内容类型上添加标头的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！