How to reference to a response object with swagger?

Question

I can do this:

parameters:
  avatarSizeParam:
    name: size
    in: query
    description: Size of avatar.
    enum: [32, 64]
    required: false
    type: integer
    format: int32

paths:
  /my/path/avatar:
    get:
      parameters:
        - $ref: '#/parameters/avatarSizeParam'

Good. Swagger defines a parameters key where you can define Parameter Objects to be reused. It also defines a responses key, where you can define Response Objects like so:

responses:
  notFoundResponse:
    description: Entity not found.
    schema:
      $ref: '#/definitions/schema404'

So I assumed I could expand my previous path definition to the following

paths:
  /my/path/avatar:
    get:
      parameters:
        - $ref: '#/parameters/avatarSizeParam'
      responses:
        - $ref: '#/responses/notFound'

This doesn't seem to work however. I went back to the spec for an Operations Object and noticed that parameters can be a Reference Object, but responses cannot.

What is the point of allowing a Responses Definitions Object (responses on the top-most level) if you can't reference the items there? Is there a way to do so?

Answer 1

If you see here, you have to define HTTP Status Code as a key, then the correct syntax is:

paths:
  /my/path/avatar:
    get:
      parameters:
        - $ref: '#/parameters/avatarSizeParam'
      responses:
        404:
          $ref: '#/responses/notFound'