How do I override example for specific properties in components in OpenAPI? - openapi

Question

Here's the minimal working example:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
paths:
/pets:
get:
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
components:
schemas:
Pet:
type: object
required:
- customName
properties:
genericName:
type: string
example: Alex
customName:
type: string
example: Ivanov
I would like to use a component Pet for the spec above yet I would like to be able to override an example for customName (the reason is it's like a URL in my real example and I'd like it be specific and it's based on the current resource but the component itself is shared among multiple resources if that makes sense).
I tried #1:
...
application/json:
schema:
$ref: "#/components/schemas/Pet"
example:
customName: IvanovOverride
components:
...
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Pet"
example:
properties:
customName: IvanovOverride
and #3:
schema:
allOf:
- $ref: "#/components/schemas/Pet"
- properties:
customName:
example: IvanovOverride
but they all didn't work on Swagger Editor (the doc always showed "Ivanov" as an example).

Answer 1

If you use OpenAPI 3.1, and you have the necessary tooling supporting it, you can use the $dynamicAnchor and $dynamicRef for solving the problem.
Example:
openapi: "3.1.0"
info:
version: 1.0.0
title: Swagger Petstore
paths:
/pets:
get:
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/PetWithFirstExampleName"
components:
schemas:
PetWithFirstExampleName:
properties:
customName:
example: firstExampleName
$dynamicAnchor: customNameExample
$ref: "#/components/schemas/Pet"
Pet:
type: object
$dynamicRef: customNameExample
required:
- customName
properties:
genericName:
type: string
example: Alex
customName:
type: string
# example is provided by the schema referenced by $dynamicRef
Note: this is a quite new feature of json schema and OpenAPI, so you can easily run into problems with the implementations.
Note 2: yours is an approximately similar usecase as this one in the official json schema test suite.