SwaggerHub - components/responses/example instead of components/schemas/example?

Question

I'm creating documentation for a RESTful API in SwaggerHub, however, I've noticed that I can't use the structure components/responses/example to display that example later as a response for a particular API path.

I know that components/schemas/example can be used, but I would prefer to distinguish between what is a schema and what is a response.

Have I missed something?

  schemas:
    CommonResponseSchema:
      description: Schema for common response structure
      type: object
      properties:
        success:
          type: boolean
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
  responses:
    Registered:
      description: Successfully registered user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonResponseSchema'
          example:
            success: false
            message: You have been successfully registered
      

Paths:

paths:
  /api/auth/register:
    post:
      summary: Register new user
      description: Register a new user with a unique email address.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Registration'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Registered'

My question is, why can't the example from components/responses/example be displayed in this case? I know that the alternative is to create a schema, but if there's another solution that is more suitable, I would prefer to use that.

Thank you.

Answer 1

To achieve my goal, I changed

      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Registered'

into

responses:
  '201':
      $ref: '#/components/responses/Registered'

Answer 2

to properly reference the response body, you need to nest the $ref inside the response code mapping value.

responses:
  '200':  # <--- this is missing in your reply
    $ref: '#/components/responses/Registered'