How to define headers in a swagger domain

Question

I'm trying to define some reusable elements in a SwaggerHub domain but can't figure out how to define headers.

I've tried a few things but they all produce errors, such as:

$refs cannot match any of the following: "#/definitions", "#/parameters"
should be a object
requires property "type"
additionalProperty "$ref" exists in when not allowed

Full example here: 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

Related: [Swagger header definitions](https://stackoverflow.com/q/40223429/113116), [Swagger / Open API 2.0 can I declare a common response header?](https://stackoverflow.com/q/35218774/113116) — Helen, Dec 14 '18 at 10:23

Helen · Accepted Answer · 2019-03-22T15:56:30.390

The bad-request response definition is the correct one, and other responses should be changed to look the same. That is, the response headers must be defined inline – this is a limitation of the OpenAPI 2.0 Specification, it does not support $ref'erencing response headers.

$ref'erencing response headers is possible in OpenAPI 3.0, but as of this writing (December 2018) SwaggerHub does not support OAS3 syntax in domains yet.

As for "Could not render this component", ~~this is a display bug in SwaggerHub. Send a bug report via the in-app support chat. That said, API definitions that use responses from domains are rendered correctly.~~ UPD: this has been fixed as of February 2019.

Shame about not being able to $ref headers, that really hampers the usefulness of reusable definitions. I will look into OAS3, thanks — batwad, Dec 14 '18 at 11:12

How to define headers in a swagger domain

1 Answers1