fix(asyncapi): preserve shared references when saving parsed spec files - #445
Merged
Conversation
Parsed AsyncAPI v3 documents contain shared (non-circular) references: each operation's dereferenced channel is the same object as the entry under the root channels object. The circular-reference-safe serializer treated any already-seen object as a cycle and replaced it with $ref: '#', producing a spec file that fails AsyncAPI validation and renders as a blank page in EventCatalog. Track ancestors instead of every object seen so shared references are preserved and only true cycles are replaced with a $ref. Closes event-catalog/eventcatalog#2745
🦋 Changeset detectedLatest commit: 9ff1764 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
The Version Packages commit bumped generator-apicurio's dependency on @eventcatalog/generator-openapi to >=9.0.0 without regenerating the lockfile, so every CI job fails at install with ERR_PNPM_OUTDATED_LOCKFILE (also failing on main).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes event-catalog/eventcatalog#2745 — AsyncAPI pages rendering as a blank white page in EventCatalog.
Root cause
Parsed AsyncAPI v3 documents contain shared (non-circular) object references: each operation's dereferenced
channelis the same JS object as the entry under the rootchannelsobject. The circular-reference-safe serializer introduced in #364 (safeStringify, released in 6.1.1) tracked every object it had ever seen, so it treated these shared references as cycles and collapsed them into$ref: '#'— a reference to the document root.With
saveParsedSpecFile: true, the resulting spec file fails AsyncAPI validation (asyncapi3-required-operation-channel-unambiguityplus cascading errors) when EventCatalog re-parses it at build time, soparsed.documentis undefined and the AsyncAPI page renders completely blank.Fix
Track ancestors instead of every object seen: shared references are serialized inline, and only true cycles (e.g. the oneOf/allOf discriminator patterns from #364) are replaced with a
$ref. The YAML path (yaml.dump) gets the same cycle-breaking pre-pass so circular schemas can no longer crash it.Testing
operationsreferencingchannels, external payload schema$refs) that asserts the saved spec file contains no$ref: "#"and re-parses as a valid AsyncAPI document — fails on the old code, passes with the fix