Swagger Syntax: How to reference a model definition from a reusable response

Question

New to swagger here. I've gone through the swagger primer and as far as I can tell, my example below should work.

My response types are just arrays of different structs (these structs are defined in the global definitions section to reduce bloat because they may be nested, and therefore get reused).

Here's my definition:

consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
swagger: '2.0'
[...Additional details excluded...]

paths:
  /first:
    get:
      responses:
        '200':
          $ref: '#/responses/response1'
  /second:
    get:
      responses:
        '200':
          $ref: '#/responses/response2'


definitions:
  ObjectA:
    type: object
    properties:
      listOfObjBs:
        type: array
        items:
          $ref: '#/definitions/ObjectB'
  ObjectB:
    type: object
    properties:
      listOfObjCs:
        type: array
        items:
          $ref: '#/definitions/ObjectC'
  ObjectC:
    description: A build
    type: object
    properties:
      someNumericData:
        type: integer
        format: int64

responses:
  response1:
    description: There are 2 types of responses, this is the first kind.
    schema:
      type: object
    headers:
      data: 
        type: array
        items:
          $ref: '#/definitions/ObjectA'
  response2:
    description: This is the second kind.
    schema:
      type: object
    headers:
      data:
        type: array
        items:
          $ref: '#/definitions/ObjectC'

However, I'm running into validation issues in the swagger web editor.

Schema error at responses['response1'].headers['data'].items should NOT have additional propertiesadditionalProperty: $ref

Semantic error at responses.response1.headers.data.items.$ref items $refs cannot match any of the following: "#/definitions", "#/parameters"

Schema error at responses['response2'].headers['data'].items should NOT have additional properties additionalProperty: $ref

Semantic error at responses.response2.headers.data.items.$ref items $refs cannot match any of the following: "#/definitions", "#/parameters"

It looks like I'm using the json references incorrectly, but I'm not sure why.

I've also tried putting response1 and response2 in the definitions section and referencing them directly (e.g. pointing the $ref under paths directly at '#/definitions/response1' instead of '#/responses/response1'). But I get an error from the editor saying that I can't reference definitions directly.

What's the correct way to structure this definition?

Answer 1

Responses with a body have a schema. To reference a model definition, use the $ref reference as the value of the schema:

responses:
  response1:  # <--- This node is on the same level as the status codes '200'/'404' etc.
    description: There are 2 types of responses, this is the first kind.
    schema:
      $ref: '#/definitions/ObjectA'

      # Or if the response is an array:
      # type: array
      # items:
      #   $ref: '#/definitions/ObjectA'


  response2:
    description: This is the second kind.
    schema:
      $ref: '#/definitions/ObjectC'

The error in your example was putting the references under headers. The headers section defines the HTTP headers of the response, such as X-RateLimit or Set-Cookie, and not the actual body payload.

  response1:
    description: There are 2 types of responses, this is the first kind.
    schema:
      type: object

    # Errors were caused by this
    headers:
      data: 
        type: array
        items:
          $ref: '#/definitions/ObjectA'