How can I inline example field in OpenAPI spec? - openapi

Question

I've got an OpenAPI schema (edited it to be a minimal working example):
---
openapi: 3.0.0
info:
title: Players API
version: 0.0.1-alpha1
paths:
/players/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Player'
- type: object
required:
- id
properties:
spec:
type: object
required:
- display_name
components:
schemas:
Player:
type: object
properties:
spec:
$ref: '#/components/schemas/PlayerSpec'
additionalProperties: false
PlayerSpec:
type: object
properties:
display_name:
type: string
description: The name of the player.
example: LeBron
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
additionalProperties: false
PlayerReference:
type: object
required:
- id
properties:
id:
type: string
example: 'lebron-23'
and after I run: redoc-cli bundle example.yaml to generate the docs I can see:
(basically id: lebron-23 is there -- i.e., the docs look as expected).
The problem is in order to make it work I had to add example: 'lebron-23' to the definition of a generic PlayerReference component but I'd rather move this example: 'lebron-23' line to this section instead:
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
<-------- add id.example here or something

Answer 1

Since environment is an object, an object-level example would look like this:
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
example:
id: lebron-23
This example will probably override any examples from allOf subschemas (rather than merge with them), so make sure to include all property values you want to see in this example.