Discussions

Ask a Question
Back to All

OpenAPI Reusable Responses with Examples loading the first time but disappearing when I click another endpoint

I'm using shared Responses definitions (with a shared ApiError schema) for error responses. I added examples on all of them, and as per OpenAPI spec, the "examples" under "responses.content.application/json" should override whatever was set as examples on the schema. (See: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)

It loads the response examples at first when I enter the documentation, however, when I click on another endpoint they disappear, even if I click back on the endpoint that was showing those examples. If I reload the page on any endpoint, they show again.

I saw if I stop using common definitions for the responses and put the response body + examples in each path, they do show consistently, but that means duplicating a lot of specification (for each error + endpoint), which isn't ideal, as well as the fact the page refresh shows at first, which seems to me to be some sort of bug on Readme.io's end.

See Images:

When I enter the page/Refresh the page:

When I enter another endpoint that should also have the response examples:

When I go click back on the original endpoint:

My specification is valid per OpenAPI's 3.0.3 Specification, but the section used is as follows:

paths:
	/rewards/{rewardId}:
...
    delete:
      summary: Cancel Reward
      operationId: cancelReward
      parameters:
        - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        '204':
          description: Reward Cancelled
          $ref: '#/components/responses/NoContent'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '401': 
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
...
components:
	...
  responses:
  	...
    InternalServerError:
      description: Internal Server Error
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          examples:
            response:
              value: 
                status: 500
                message: 'An unexpected error occurred on the server'
                code: 'INTERNAL_SERVER_ERROR'
    ...


What should I do to fix this? Or is this an issue on Readme.io's end? I tried clearing cache with no success.