如何在招摇域中定义标头

Question

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

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

• $refs 不能匹配以下任何一个：“#/definitions”， "#/参数"
• 应该是一个对象
• 需要属性“类型”
• 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 响应定义是正确的，其他响应应更改为相同。也就是说，响应头必须内联定义——这是 OpenAPI 2.0 规范的限制，它不支持 $ref'erencing 响应头。

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

至于“无法渲染此组件”，这是 SwaggerHub 中的显示错误。通过应用内支持聊天发送错误报告。也就是说，使用来自域的响应的 API 定义可以正确呈现。 UPD：此问题已于 2019 年 2 月修复。