Skip to content

fix(json-schema-5-samples): unwrap schema example referencing components.examples#10884

Open
yogeshwaran-c wants to merge 1 commit into
swagger-api:masterfrom
yogeshwaran-c:fix/example-ref-value-keyword-5748
Open

fix(json-schema-5-samples): unwrap schema example referencing components.examples#10884
yogeshwaran-c wants to merge 1 commit into
swagger-api:masterfrom
yogeshwaran-c:fix/example-ref-value-keyword-5748

Conversation

@yogeshwaran-c
Copy link
Copy Markdown

Description

When a schema property's example keyword is {$ref: '#/components/examples/X'}, the rendered example incorrectly includes a value: wrapper key.

Root cause

swagger-client's ref resolver (refs.js) substitutes the resolved Example Object verbatim — only response/requestBody/parameter examples[*].value paths are on its skip list. So a schema-level example: { \$ref: '#/components/examples/X' } is replaced with { value: <user data>, \$\$ref: '#/components/examples/X' }.

sampleFromSchemaGeneric in src/core/plugins/json-schema-5-samples/fn/index.js then reads that object as the literal sample, leaving the value: wrapper visible in the rendered output. The same example referenced from a response's examples: block does not hit this code path and renders correctly (the asymmetry described in the issue).

Fix

A new helper unwrapTopLevelExampleReference checks whether the top-level example object has both a \$\$ref matching #/components/examples/ and an own value key. Only that exact shape (which swagger-client injects deterministically for resolved Example Objects) is unwrapped; everything else passes through untouched.

The fix is intentionally conservative:

  • It only fires when the resolver's distinctive Example-Object marker (\$\$ref pointing into #/components/examples/) is present.
  • It is top-level only — nested occurrences are left to sanitizeRef exactly as before, so existing tests at test/unit/core/plugins/json-schema-5-samples/fn/index.js:294 and :324 are unaffected.
  • User-authored objects with a literal value key (no \$\$ref) or with a \$\$ref pointing elsewhere are preserved verbatim.

Motivation and Context

Fixes #5748.

How Has This Been Tested?

  • Unit: updated the existing root-level \$\$ref test in test/unit/core/plugins/json-schema-5-samples/fn/index.js to expect the unwrapped shape, and added two new negative tests (no \$\$ref; \$\$ref pointing outside #/components/examples/). Full file: 121 tests pass.
  • Cypress (CI): new fixture test/e2e-cypress/static/documents/bugs/5748.yaml reproduces the issue's repro spec; new spec test/e2e-cypress/e2e/bugs/5748.cy.js asserts the rendered example contains the inner keys (Individual, Variant) and does not contain the \"value\": wrapper.
  • Lint: eslint --max-warnings 0 clean on changed files.

Checklist

  • Bug fix (non-breaking change which fixes an issue)
  • My change requires no documentation update
  • I have added tests to cover my changes
  • All new and existing tests passed

…nts.examples

When a schema property's `example` keyword is `{$ref: '#/components/examples/X'}`,
swagger-client substitutes the resolved Example Object verbatim, leaving
`{value: <user data>, $$ref: '#/components/examples/X'}`. The sample generator
then rendered the literal `value:` wrapper instead of the actual example data.

Add `unwrapTopLevelExampleReference` which, when the top-level example object
has both a `$$ref` pointing into `#/components/examples/` and a `value` key,
returns the inner `value`. This is a no-op for any other shape (including
nested occurrences, user-authored objects that happen to have a `value` key,
or `$$ref`s pointing elsewhere), so it cannot affect normal sample generation.

Fixes swagger-api#5748
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Example reused in a property is rendering the value keyword

1 participant