How to reference a response object with swagger?

Question

I can do it:

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 for reuse. It also defines a responses key, where you can define Response Objects like this:

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

So, I assumed that I could extend my previous path definition to the next

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

However, this does not work. I went back to the specification for the Operations Object and noticed that parameters can be a reference object, but responses cannot.

What is the point of creating a Response Definition object ( responses at the highest level) if you cannot reference objects there? Is there any way to do this?

Answer 1

If you see here , you need to define the 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'