Skip to content

fix(oas3): show request body description for file upload content types#10836

Open
yogeshwaran-c wants to merge 4 commits intoswagger-api:masterfrom
yogeshwaran-c:fix/show-request-body-description-file-upload
Open

fix(oas3): show request body description for file upload content types#10836
yogeshwaran-c wants to merge 4 commits intoswagger-api:masterfrom
yogeshwaran-c:fix/show-request-body-description-file-upload

Conversation

@yogeshwaran-c
Copy link
Copy Markdown

Description

When a request body uses a content type like application/octet-stream that triggers file upload mode, the description from the requestBody object was not displayed. The early return in the file upload branch skipped the description rendering that exists for other content types.

This change renders the requestBody.description (via Markdown component) above the file input or the "Example values are not available" message, consistent with how descriptions are shown for application/json, multipart/form-data, and other content types.

Motivation and Context

Fixes #5637

Users who document their file upload endpoints with descriptions (e.g., "A zip file containing files that will be unzipped") expect those descriptions to be visible in Swagger UI, regardless of the content type.

How Has This Been Tested?

  • Verified that the Markdown component and requestBodyDescription variable are already available in scope at the point of the change
  • The pattern { requestBodyDescription && <Markdown source={requestBodyDescription} /> } is reused from lines 146-148 and 276-278 in the same file
  • Both the execute and non-execute branches now render the description

Screenshots (if appropriate):

N/A - description text is now visible above file upload inputs

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.

When a request body uses a content type like application/octet-stream
that triggers file upload mode, the description from the requestBody
object was not being displayed. Instead, only the "Example values are
not available" message was shown (in non-execute mode) or just the
file input (in execute mode).

This renders the requestBody description above the file input or
the example-not-available message, consistent with how descriptions
are shown for other content types.

Fixes swagger-api#5637
@yogeshwaran-c yogeshwaran-c force-pushed the fix/show-request-body-description-file-upload branch from 9c819d3 to 8d1d1ed Compare April 20, 2026 08:57
@lukaszzazulak
Copy link
Copy Markdown
Contributor

@yogeshwaran-c please add tests for you changes

@yogeshwaran-c
Copy link
Copy Markdown
Author

@lukaszzazulak Added unit tests in 527322c (see test/unit/core/plugins/oas3/components/request-body.jsx).

The suite covers the fix end-to-end:

  • renders the requestBody.description Markdown above the file input when the content type triggers file upload (application/octet-stream) and isExecute is true
  • renders the description above the "Example values are not available" message when isExecute is false
  • does not render a Markdown block when requestBody has no description (both isExecute branches) — guards the requestBodyDescription && ... conditional so we don't accidentally emit an empty wrapper or regress when the field is missing

Run:

npm run test:unit -- test/unit/core/plugins/oas3/components/request-body.jsx

4/4 passing locally. Lint is clean (npx eslint --max-warnings 0 ...).

@lukaszzazulak
Copy link
Copy Markdown
Contributor

lukaszzazulak commented Apr 21, 2026

@yogeshwaran-c please add e2e test in Cypress, there are already existing similar tests, have a look and add similar tests to cover new cases added here

@yogeshwaran-c
Copy link
Copy Markdown
Author

@lukaszzazulak thanks for the review -- added Cypress e2e coverage in f0ad27c.

New files:

  • test/e2e-cypress/static/documents/features/oas3-request-body-file-upload-description.yaml -- spec fixture covering the file-upload content types affected by this PR, each with a Markdown requestBody.description (plus a control path with no description).
  • test/e2e-cypress/e2e/features/plugins/oas3/request-body-file-upload-description.cy.js -- companion to the existing request-body-upload-file.cy.js, asserting the description renders for each file-upload variant both before and after Try it out is enabled (covering both isExecute branches in the component change).

Covered content types:

  • application/octet-stream (with schema)
  • image/png
  • application/octet-stream with an empty Media Type Object
  • application/x-custom with format: binary
  • control: file upload without a description -- asserts no stray .markdown node renders

Each suite asserts:

  • the .opblock-section-request-body .opblock-description-wrapper .markdown block exists and contains the expected text
  • that Markdown is actually rendered (e.g. <strong>/<em> produced from **bold**/*italic*)
  • the existing behavior is preserved: the italic fallback text pre-Try-It-Out and the file input post-Try-It-Out both still appear alongside the new description

Let me know if you'd like additional variants or different selectors.

@lukaszzazulak
Copy link
Copy Markdown
Contributor

lukaszzazulak commented Apr 22, 2026

@yogeshwaran-c tests are failing; please make sure tests pass locally (for all of your PRs)

OAS3 wrap-components/markdown.jsx renders with class renderedMarkdown,
not the core markdown class; the prior selectors never matched and all
eight new e2e cases timed out in CI.
@yogeshwaran-c
Copy link
Copy Markdown
Author

@lukaszzazulak you were right — the new e2e spec was using the core Markdown class (.markdown) but the OAS3 wrap-components/markdown.jsx renders with class renderedMarkdown, so the selector never matched and all eight cases timed out.

Fixed in 247ea14 by switching the selector to .opblock-description-wrapper .renderedMarkdown, consistent with existing OAS3 specs like test/e2e-cypress/e2e/features/schema-form.cy.js.

Verified locally:

OpenAPI 3.0 Request Body description on file upload content types
  application/octet-stream (with schema)
    √ renders the Markdown description before Try it out is enabled
    √ renders the Markdown description after Try it out is enabled
  image/png
    √ renders the Markdown description before Try it out is enabled
    √ renders the Markdown description after Try it out is enabled
  application/octet-stream with empty Media Type Object
    √ renders the Markdown description before Try it out is enabled
    √ renders the Markdown description after Try it out is enabled
  schema type string and format binary
    √ renders the Markdown description before Try it out is enabled
    √ renders the Markdown description after Try it out is enabled
  file upload without a requestBody description
    √ does not render a Markdown block when description is absent (before Try it out)
    √ does not render a Markdown block when description is absent (after Try it out)

10 passing (21s)

@lukaszzazulak lukaszzazulak self-requested a review April 22, 2026 12:11
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.

Request body descriptions are not shown when the input type is a file upload

2 participants