Recursive $refs in example not resolving
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.5k
- Forks
- 228
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 48
Description
Describe the bug
I'm trying to define and reuse some "example" defined in yaml files for multiple models, but redocly doesn't seems to resolve them correctly.
To Reproduce
Consider this openapi.yaml file:
openapi: 3.0.0
info:
title: Test device API
version: "0.0.1"
description: |
This is a test description.
servers:
- url: /
description: Server
paths:
/test:
get:
tags:
- Test
summary: Test endpoint
operationId: getTest
responses:
"200":
description: The test response
content:
application/json:
schema:
$ref: ./TestSchema.yaml
example:
$ref: ./TestSchemaExample.yaml
components:
schemas:
TestSchema:
$ref: ./TestSchema.yaml
TestSchema.yaml
type: object
properties:
testField:
$ref: ./TestField.yaml
anotherField:
$ref: ./AnotherField.yaml
TestField.yaml
type: string
description: Test String
example: "Test"
AnotherField.yaml
type: string
description: Test String
example: "Another"
I'd like to define
TestSchemaExample.yaml
testField:
$ref: ./TestFieldExample.yaml
anotherField: "AnotherExample"
TestFieldExample.yaml
"Test"
Running
$ redocly bundle openapi.yaml --output dist/openapi.yaml --ext yaml
Results in
openapi: 3.0.0
info:
title: Test device API
version: 0.0.1
description: |
This is a test description.
servers:
- url: /
description: Server
paths:
/test:
get:
tags:
- Test
summary: Test endpoint
operationId: getTest
responses:
'200':
description: The speaker preset
content:
application/json:
schema:
$ref: '#/components/schemas/TestSchema'
example:
testField:
$ref: ./TestFieldExample.yaml
anotherField: AnotherExample
components:
schemas:
TestSchema:
type: object
properties:
testField:
$ref: '#/components/schemas/TestField'
anotherField:
$ref: '#/components/schemas/AnotherField'
TestField:
type: string
description: Test String
example: Test
AnotherField:
type: string
description: Test String
example: Another
And the file $ref is kept for the testField example.
Expected behavior
I'd like testField in the example to resolve the assigned ref.
Redocly version(s)
2.12.5
Node.js version(s)
v22.15.0
OS, environment
Ubuntu 24.04
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the issue with the provided openapi.yaml and the TestSchemaExample.yaml, TestFieldExample.yaml, and related fixture files using the redocly bundle command. Trace how the bundle handles the nested example $ref; done means the testField reference is resolved in the bundled output rather than left as a file path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript, yaml
- Domain
- api, cli
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100