Skip to content

feat(oas2): support x-examples in body parameter request preview#10864

Open
yogeshwaran-c wants to merge 1 commit into
swagger-api:masterfrom
yogeshwaran-c:fix/oas2-x-examples-body-param
Open

feat(oas2): support x-examples in body parameter request preview#10864
yogeshwaran-c wants to merge 1 commit into
swagger-api:masterfrom
yogeshwaran-c:fix/oas2-x-examples-body-param

Conversation

@yogeshwaran-c
Copy link
Copy Markdown

Description

Adds support for the OpenAPI 2.0 x-examples vendor extension on body parameters. When a body parameter declares an x-examples map 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:

  1. x-examples.default
  2. The first entry in the x-examples map (preserving spec order)
  3. The existing schema-derived sample (current behaviour)

String examples are emitted verbatim; structured values are pretty-printed as JSON.

Motivation and Context

x-examples is widely produced by OAS 2.0 tooling such as springfox, swagger-jaxrs, and io.swagger.models.parameters.AbstractSerializableParameter (which serialises the user-defined example field as x-examples). Authors who set x-examples reasonably expect Swagger UI to surface those values, but until now they were silently dropped because ParamBody.updateValues only consulted value/value_xml before falling back to fn.getSampleSchema.

Closes #3233. The original issue includes a maintainer ack from @shockey on this exact code path:

Your change to param-body.jsx seems like a step in the right direction - if you'd like to open a PR for this feature, I'd be happy to review it.

This change is conservative on purpose:

  • It only fires when the parameter has no value/value_xml of its own, so it cannot override anything the user has typed or anything Swagger UI has already populated.
  • It does not touch OAS 3.x, which has first-class example/examples support and a different code path (parameter-row.jsx + ExamplesSelectValueRetainer).
  • It leaves the x-examples data structure untouched in state — it only consults it when picking the initial preview value.

How Has This Been Tested?

  • New Jest unit tests in test/unit/components/param-body.jsx cover six scenarios: existing user value wins, falls back to generated sample when there are no examples, prefers x-examples.default, falls back to the first entry when default is absent, passes string examples through verbatim, and ignores empty x-examples maps.
  • New Cypress e2e spec test/e2e-cypress/e2e/bugs/3233.cy.js (with fixture test/e2e-cypress/static/documents/bugs/3233.yaml) loads an OAS 2.0 document with x-examples and asserts that the rendered preview (.body-param__example) and the Try it out textarea (textarea.body-param__text) both contain the example payload.
  • Local results: npm run test:unit -- test/unit/components/param-body.jsx → 6/6 pass; existing parameter-row tests 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 declaring x-examples on a body parameter, in which case the example payload now appears inside the existing .body-param__example block.

Checklist

My PR contains...

  • No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
  • Dependency changes (any modification to dependencies in package.json)
  • Bug fixes (non-breaking change which fixes an issue)
  • Improvements (misc. changes to existing features)
  • Features (non-breaking change which adds functionality)

My changes...

  • are breaking changes to a public API (config options, System API, major UI change, etc).
  • are breaking changes to a private API (Redux, component props, utility functions, etc.).
  • are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
  • are not breaking changes.

Documentation

  • My changes do not require a change to the project documentation.
  • My changes require a change to the project documentation.
  • If yes to above: I have updated the documentation accordingly.

Automated tests

  • My changes can not or do not need to be tested.
  • My changes can and should be tested by unit and/or integration tests.
  • If yes to above: I have added tests to cover my changes.
  • If yes to above: I have taken care to cover edge cases in my tests.
  • All new and existing tests passed.

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
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 request string is not populated

1 participant