Skip to content

fix(reference): skip transcluded Example value in mutual-exclusion check - #5191

Open
maruthang wants to merge 1 commit into
swagger-api:mainfrom
maruthang:fix/example-external-value-path-item-ref
Open

maruthang wants to merge 1 commit into
swagger-api:mainfrom
maruthang:fix/example-external-value-path-item-ref

Conversation

@maruthang

Copy link
Copy Markdown

Fixes #5190. Also the root cause of swagger-api/swagger-ui#10418 (and the motivation behind the now-closed swagger-api/swagger-ui#10822, per @glowcloud's review there).

Problem

When an Example Object with only externalValue sits inside an externally referenced Path Item Object, dereferencing fails with:

ExampleElement value and externalValue fields are mutually exclusive.

The PathItemElement handler dereferences the external fragment with a nested visitor, then link.replaceWiths the merged Path Item — and the outer visitor descends into the already-dereferenced subtree. The nested pass has by then transcluded externalValue into value (annotating value with ref-origin meta) while intentionally keeping externalValue, so the outer pass re-visits an Example that now has both fields and trips the mutual-exclusion guard. Without the path-level $ref there is only one traversal, hence no error.

Fix

In the ExampleElement handlers of the 3.0, 3.1, and 3.2 dereference strategies, skip elements whose value carries the ref-origin meta (i.e. the value was already transcluded by a previous pass) before applying the mutual-exclusion check. A genuine violation (both value and externalValue in source) still errors as before.

Verification

  • Reproduced the failure with the fixture from swagger-ui#10418 against @swagger-api/apidom-reference@1.11.3; with this guard applied the repro dereferences cleanly and the output is identical to the inline (no-$ref) equivalent.
  • Added regression fixtures/tests external-value-path-item-ref to the example-object dereference suites for the 3.0 and 3.1 strategies.
  • The full monorepo suite was not run locally (Windows machine constraints) — relying on CI for end-to-end validation.

When a Path Item Object is referenced with $ref from an external document,
the referenced fragment is dereferenced by a nested visitor and the merged
result is traversed again by the outer visitor. Example Objects transcluded
from externalValue intentionally contain both value and externalValue fields,
so the second traversal raised a false positive
"ExampleElement value and externalValue fields are mutually exclusive." error.

The value element transcluded from externalValue is annotated with ref-origin
meta, so already dereferenced Example Objects are now skipped.

Fixes swagger-api/swagger-ui#10418

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant