How to extend a defined response in OpenAPI? - swagger

Question

I want to extend the "200SuccessDefault" response with a schema or example.
paths:
/home:
...
responses:
200:
$ref: '#/components/responses/200SuccessDefault'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PieChartElement'
examples:
PieChart:
$ref: '#/components/examples/PieChart_1'
This approach runs into an error, the schema and examples fields are ignored:
Sibling values alongside $refs are ignored. To add properties to a $ref, wrap the $ref into allOf, or move the extra properties into the referenced definition (if applicable).
I tried allOf:
paths:
/home:
responses:
200:
allOf:
- $ref: '#/components/responses/200SuccessDefault'
- content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PieChartElement'
examples:
PieChart:
$ref: '#/components/examples/PieChart_1'
This approach runs into the error:
should NOT have additional properties additionalProperty: allOf
should have required property 'description' missingProperty: description

Answer 1

You cannot extend a referenced response object. But, you can use a shared schema object and extend it utilizing allOf within schema.
Inside allOf you can put:
your $ref
a new type extending your default response
If you want to give an example of an entire extended response (JSON), just put it into "application/json".
An example of OpenAPI would be:
"202":
description: Extended response sample
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/application"
- type: object
properties:
anotherProperty:
type: string
maxLength: 200
example: "Property example"
example: {id: 1234, anotherProperty: "Hello"}