How to reference response components in OpenAPI?

Question

I am writing an OpenAPI definition for my API. I am using components for responses, but Swagger Editor shows an error when I try to reference these components:

responses:
  - $ref: '#/components/responses/401'
  - $ref: '#/components/responses/400'

What is the correct way to reference response components?

Answer 1

The correct way to reference response components is:

responses:
  '400':
    $ref: '#/components/responses/400'
  '401':
    $ref: '#/components/responses/401'

That is, responses is a map (not an array/list) where the keys are HTTP status codes and the values are response definitions.

Can you override the response description when referencing the component?

This is possible in OpenAPI 3.1, but not in earlier versions. Put the new description alongside the $ref:

# openapi: 3.1.0

responses:

  '400':
    $ref: '#/components/responses/400'
    description: This description overrides that of the referenced response.

  '401':
    $ref: '#/components/responses/401'
    description: This description overrides that of the referenced response.