feat(oas2): support x-examples in body parameter request preview#10864
Open
yogeshwaran-c wants to merge 1 commit into
Open
feat(oas2): support x-examples in body parameter request preview#10864yogeshwaran-c wants to merge 1 commit into
yogeshwaran-c wants to merge 1 commit into
Conversation
The OAS 2.0 `x-examples` vendor extension is a popular way to attach sample values to body parameters (used by tools such as swagger-jaxrs and io.swagger.models). Until now Swagger UI ignored those values entirely and rendered the auto-generated schema sample instead, leaving developers without an easy way to surface a realistic request body. When the parameter has no user-provided value, ParamBody now uses the `x-examples` "default" entry (or the first entry) as the initial body value, falling back to the generated sample when no `x-examples` are present. String examples are passed through verbatim; structured values are pretty-printed as JSON. Adds Jest coverage for ParamBody and a Cypress e2e fixture/spec that exercises the rendered example and the "Try it out" textarea for an OAS 2.0 spec with `x-examples`. Refs swagger-api#3233
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
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.
Description
Adds support for the OpenAPI 2.0
x-examplesvendor extension on body parameters. When a body parameter declares anx-examplesmap and the user has not yet supplied a value, Swagger UI now renders that example as the request body preview (and pre-fills the textarea once "Try it out" is enabled) instead of the auto-generated schema sample.Lookup order:
x-examples.defaultx-examplesmap (preserving spec order)String examples are emitted verbatim; structured values are pretty-printed as JSON.
Motivation and Context
x-examplesis widely produced by OAS 2.0 tooling such asspringfox,swagger-jaxrs, andio.swagger.models.parameters.AbstractSerializableParameter(which serialises the user-definedexamplefield asx-examples). Authors who setx-examplesreasonably expect Swagger UI to surface those values, but until now they were silently dropped becauseParamBody.updateValuesonly consultedvalue/value_xmlbefore falling back tofn.getSampleSchema.Closes #3233. The original issue includes a maintainer ack from @shockey on this exact code path:
This change is conservative on purpose:
value/value_xmlof its own, so it cannot override anything the user has typed or anything Swagger UI has already populated.example/examplessupport and a different code path (parameter-row.jsx+ExamplesSelectValueRetainer).x-examplesdata structure untouched in state — it only consults it when picking the initial preview value.How Has This Been Tested?
test/unit/components/param-body.jsxcover six scenarios: existing user value wins, falls back to generated sample when there are no examples, prefersx-examples.default, falls back to the first entry whendefaultis absent, passes string examples through verbatim, and ignores emptyx-examplesmaps.test/e2e-cypress/e2e/bugs/3233.cy.js(with fixturetest/e2e-cypress/static/documents/bugs/3233.yaml) loads an OAS 2.0 document withx-examplesand asserts that the rendered preview (.body-param__example) and theTry it outtextarea (textarea.body-param__text) both contain the example payload.npm run test:unit -- test/unit/components/param-body.jsx→ 6/6 pass; existingparameter-rowtests still pass;npm run cy:run -- --spec "test/e2e-cypress/e2e/bugs/3233.cy.js"→ 2/2 pass;npm run build:core→ success.Screenshots (if appropriate)
Not applicable — behaviour is identical for specs without
x-examples. The change is observable only when an OAS 2.0 spec opts in by declaringx-exampleson a body parameter, in which case the example payload now appears inside the existing.body-param__exampleblock.Checklist
My PR contains...
src/is unmodified: changes to documentation, CI, metadata, etc.)package.json)My changes...
Documentation
Automated tests