Swagger header 定义

Question

我似乎无法找到是否可以声明一个 header object 以便在响应 header 中重用它，有定义 [=21] 的示例=]s 用于响应模式，但它不会转换为响应 headers。我只设法做出这样的可重用响应 object：

responses:
  DownloadOk:
    description: Dowload Ok
    headers:
      Content-Length:
        description: response length
        type: integer 
      Document-Length:
        description: document length
        type: integer

但正如我所说，我只想保留 header 部分。

这里是我想使用它的地方：

responses:
    200:
      description: Dowload Ok
      headers:
        $ref: '#/definitions/DowloadOk'

Answer 1

根据 Swagger/OpenAPI 规范，您不能。 Definitions must contain Schema Objects, and those do not allow arbitrary properties, but specific subset of JSON Schema (see the link).

您能够定义 Response Object and reference that, because the Swagger Object 具有全局 responses 属性。 headers 没有这样的事情。反正现在不行。请求这样的功能可能是值得的。

Answer 2

我遇到过同样的问题。他们在文件中声明；

Note that, currently, OpenAPI Specification does not permit to define common response headers for different response codes or different API operations. You need to define the headers for each response individually.

请参阅 Describing Responses 中的 响应 Header 部分。

Swagger header 定义

Swagger header definitions

swagger

swagger-ui

swagger-2.0