Redocly / Redocly/redocly-cli

Recursive $refs in example not resolving

Open
#2,472 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.