Redocly / Redocly/redocly-cli

$ref lines not resolving during bundle - is there a limit to the number of $ref lines you can use in the bundle function?

Open
#2,348 11 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

$ref p3 Type: Bug
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Describe the bug

I am using the bundle function to construct an Open API yaml file and am getting stuck with a single $ref line not resolving correctly & being updated to correct syntax in the bundled output file, no matter what I try. It seems that for whichever endpoint comes second in paths-base.yaml, one of the $ref lines just won't resolve. The bundled output contains the following:

If you swap the order of the endpoints being declared, this issue will swap to the other endpoint.

My only thought is that there is a limit to the number of $ref references the bundle function can handle?

To Reproduce
Steps to reproduce the behavior:

  1. Import attached repo
  2. Run command redocly bundle base.yaml --output bundled-api.yaml
  3. See line 224:
                $ref: ../../components/models/MatterListResponseNew.yaml

Expected behavior

The $ref should resolve like

                $ref: '#/components/schemas/PublicDocsErrorResponse'

This only happens this this $ref, however if you swap the order of the endpoints in paths-base.yaml, this resolve issue will swap to the other endpoint.

Change:

/api/v1/cards:
  $ref: ../paths/endpoints/GET-api-v1-cards.yaml
/api/v3/matters:
  $ref: ../paths/endpoints/GET-api-v3-matters.yaml

to:

/api/v3/matters:
  $ref: ../paths/endpoints/GET-api-v3-matters.yaml
/api/v1/cards:
  $ref: ../paths/endpoints/GET-api-v1-cards.yaml

Logs

PS C:\repositories\openapi-spec-sanitized-fixed> redocly bundle base.yaml --output bundled-api.yaml
bundling base.yaml...
📦 Created a bundle for base.yaml at bundled-api.yaml 32ms.

This is on the latest version of redocly cli.

Please let me know if you require any additional details.

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 running redocly bundle base.yaml --output bundled-api.yaml against the linked reproduction repository and inspect line 224 of bundled-api.yaml. Compare the two endpoint orders in paths-base.yaml and trace how their $ref entries are bundled. Done means both references resolve to the expected #/components/schemas/... syntax regardless of endpoint order.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.