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月修复。

如何在swagger域中定义标题

1 个答案: