如何在 swagger 域中定义 headers

Question

我正在尝试在 SwaggerHub 域中定义一些可重用元素，但不知道如何定义 headers。

我已经尝试了一些方法，但它们都会产生错误，例如：

$refs 无法匹配以下任何内容：“#/definitions”， "#/参数"
应该是 object
需要属性"type"
additionalProperty "$ref" 存在于不允许的情况下

完整示例在这里： https://app.swaggerhub.com/domains/batwad/domain-demo/1.0.0

definitions:
  error-list:
    description: Standard error response
    type: object
    properties:
      errors:
        type: array
        items:
          type: string
        readOnly: true

responses:
  bad-request:
    description: Bad request
    headers:
      # these don't error, but the UI docs say "Could not render this component"
      X-Transaction-ID:
        description: Transaction correlation identifier.
        type: string
      Content-Type:
        description: Must be <tt>application/json</tt>
        type: string
    schema:
      $ref: '#/definitions/error-list'

  server-error:
    description: Unexpected error
    headers:
      # says "should be an object" and "cannot match any of blablabla"
      - $ref: '#/parameters/x-transaction-id'
      - $ref: '#/parameters/content-type'
    schema:
      $ref: '#/definitions/error-list'

  service-unavailable:
    description: Service temporarily unavailable
    schema:
      $ref: '#/definitions/error-list'
    headers:
      # says "requires property 'type'" and "$ref not allowed"
      X-Transaction-ID:
        $ref: '#/parameters/x-transaction-id'
      Content-Type:
        $ref: '#/parameters/content-type'

parameters:

  x-transaction-id:
    name: X-Transaction-ID
    in: header
    description: Transaction correlation identifier.
    required: true
    type: string

  content-type:
    name: Content-Type
    in: header
    description: Must be <tt>application/json</tt>
    required: true
    type: string

Answer 1

bad-request 响应定义是正确的，应更改其他响应以使其看起来相同。也就是说，响应 headers 必须内联定义——这是 OpenAPI 2.0 规范的限制，它不支持 $ref'erencing 响应 headers.

$ref'erencing 响应 headers 是 possible in OpenAPI 3.0，但截至撰写本文时（2018 年 12 月）SwaggerHub 尚不支持域中的 OAS3 语法。

至于"Could not render this component"，~~这是SwaggerHub中的显示错误。通过 in-app 支持聊天发送错误报告。也就是说，API 使用来自域的响应的定义可以正确呈现。~~ UPD：此问题已于 2019 年 2 月修复。

如何在 swagger 域中定义 headers

How to define headers in a swagger domain

swagger

swagger-2.0

swaggerhub