Discussions
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.