openapi: referring to an existing example in a list - swagger

Question

I have an OpenAPI 3.0.0 spec with a Widget component, which includes an example section:
components:
schemas:
Widget:
properties:
id:
type: string
description:
type: string
cost:
type: float
example:
id: 1234
description: An example widget
cost: 0.10
I'm adding a Warehouse component that includes a list of Widgets. Is there a way to make use of the example on the Widget schema in the Warehouse schema? Something like:
Warehouse:
properties:
id:
type: string
location:
type: string
widgets:
type: array
items:
$ref: '#/components/schemas/Widget'
example:
id: 4321
widgets:
- $ref: '#/components/schemas/Widget'
The above didn't work. I looked at moving the example out of the Widget schema and into a #/components/examples/WidgetExample, but I still wasn't sure what the syntax would look like to refer to that.

Answer 1

The example keyword does not support $ref.
What you can do instead is change the Warehouse schema to use property-level examples for properties other than widgets, in this case the example for widgets will be "inherited" from the Widget schema. At least this is how it works in Swagger UI and Swagger Editor.
Warehouse:
properties:
id:
type: string
example: 4321 # <----
location:
type: string
example: Sample location # <----
widgets:
type: array
items:
$ref: '#/components/schemas/Widget'
Swagger UI will display the following example for Warehouse in the requests and responses:
{
"id": 4321,
"location": "Sample location",
"widgets": [
"id": 1234,
"description": "An example widget",
"cost": 0.1
]
}