Normalize request media types without a new plugin dependency by fly1d · Pull Request #1676 · PaloAltoNetworks/docusaurus-openapi-docs

fly1d · 2026-10-27T13:07:04Z

Refs #603.

Normalize media types with a theme-local helper and keep plugin-side normalization local. Parameterized forms and JSON/XML examples work consistently; API and webhook sampling prefer exact application/json, then +json, before the existing JSON-family fallback. The theme does not require a new plugin-internal export.

Include the main-branch changes through #1677, retaining its body-mode selection and named-file validation. Only final formdata mode omits the multipart boundary. Pre-encoded raw strings and nonform file uploads retain their supplied boundary and bytes. The two old unnamed multipart-file controls now use supported nonform file uploads; the raw-string multipart controls and upstream multipart validation tests remain intact.

Validation on Node 26.5.0/macOS: full yarn test passes 372 tests across 20 suites, with 35 snapshots. All three packages build without cache; strict changed-file ESLint, Prettier and diff checks pass. The builder is byte-identical to the #1677 merge, af7bee5.

Required full yarn lint still exits 2 at the existing Cypress cypress/globals configuration error. No browser or hosted CI matrix result is claimed.

Refs PaloAltoNetworks#603

sserrata

Thanks. This PR now has a merge conflict with main because of #1678 (jest.config.js, Body/index.tsx). Please rebase. The media-type handling is also incomplete. Please add one shared helper (for example, getMediaType(contentType): remove parameters, change to lower case) and use it in Body, buildPostmanRequest and the plugin. #1677 needs the same helper.

Other items (outside the diff):

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Body/index.tsx: The form checks (here and in the render branch) still compare the raw contentType with ===. multipart/form-data; boundary=x or application/x-www-form-urlencoded; charset=utf-8 still gets an empty plaintext editor. Use the parsed mediaType.
packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/buildPostmanRequest.ts: The form mode is selected by an exact match on the raw contentType. A urlencoded type that has parameters keeps the old mode.
packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts: The plugin's jsonRequestBodyExample still uses raw-key checks. application/json;charset=UTF-8 and application/problem+json; charset=utf-8 get no example, so the plugin and theme do not agree.

sserrata · 2026-10-28T19:49:48Z

-      contentType?.includes("application/json") ||
-      contentType?.endsWith("+json")
-    ) {
+    if (mediaType === "application/json" || mediaType?.endsWith("+json")) {


Regression: an exact match drops JSON handling for application/json-seq, application/jsonl and similar types that the old includes("application/json") matched. These now get an empty plaintext editor.

sserrata

Thanks for the update. The shared helper, the form branches and the json-seq fix look good. Some new problems must be fixed before merge:

Other items (outside the diff):

packages/docusaurus-plugin-openapi-docs/src/openapi/utils/utils/openapi.ts: isFormUrlEncoded still uses an exact match, so the plugin and theme do not agree for application/x-www-form-urlencoded; charset=utf-8.

sserrata · 2026-10-29T14:35:57Z

 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
 import { sampleFromSchema } from "docusaurus-plugin-openapi-docs/lib/openapi/createSchemaExample";
+import { getMediaType } from "docusaurus-plugin-openapi-docs/lib/utils/mediaType";


Peer dependency break: the theme imports docusaurus-plugin-openapi-docs/lib/utils/mediaType, which is new in this PR, but the theme peer range is still ^5.0.0. A user who upgrades only the theme gets "Module not found". Move getMediaType into the theme (for example, ApiExplorer/utils). Then the plugin change and the special Jest mappings are also not necessary. #1677 needs the same helper. The plugin version (or the existing code at openapi/utils/utils/openapi.ts:509) can stay separate.

sserrata · 2026-10-29T14:35:57Z

-          key.toLowerCase() === "application/json" ||
-          key.toLowerCase() === "application/json; charset=utf-8"
-        ) {
+        if (getMediaType(key).startsWith("application/json")) {


startsWith("application/json") now selects the first application/json* key. With {application/jsonl, application/json}, the example comes from the jsonl schema. Use an exact application/json match first, then +json. The webhook branch (line 358) has the same problem.

sserrata · 2026-10-29T14:35:57Z


+  if (body.type === "form") {
+    const mediaType = getMediaType(contentType);
+    if (mediaType === "multipart/form-data") {


A boundary= from the selected content type goes into the Content-Type header of the snippets, but the client makes its own boundary. The copied curl command then sends a body that the server cannot parse. Remove boundary from the header for formdata.

sserrata · 2026-10-29T14:35:57Z

    return;
  }

+  if (body.type === "form") {


After a mode change, the old raw, urlencoded or formdata data stays on the cloned body, and toJSON() includes it. Clear the inactive fields.

sserrata

Thanks. All review items are addressed. Note: this PR and #1677 change the same lines in buildPostmanRequest.ts, so the PR that merges second needs a rebase.

github-actions · 2026-10-30T15:56:14Z

Visit the preview URL for this PR (updated for commit a3a0963):

https://docusaurus-openapi-36b86--pr1676-ua544npm.web.app

_{(expires Fri, 06 Nov 2026 15:56:06 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

github-actions · 2026-10-30T16:01:15Z

📸 Visual Diff Report

_{Snapshot comparison against https://docusaurus-openapi.tryingpan.dev/}

Total	✅ Match	❌ Diff	⏭ Skip
228	228	0	0

Preview: https://docusaurus-openapi-36b86--pr1676-ua544npm.web.app
Diff images: https://docusaurus-openapi-36b86--pr1676-diffs-dqis7vvg.web.app/
Full HTML report: download from run artifacts

✅ No visual regressions detected.

_{Updated at 2026-10-30T16:01:14.079Z · run 40927256913}

sserrata · 2026-10-30T16:29:03Z

This PR now conflicts with main after #1677 merged (buildPostmanRequest.ts, jest.config.js, utils/mediaType.test.ts). #1677 already added utils/mediaType.ts and setBodyMode, so please rebase onto main, reuse those, and remove the duplicate mode-selection logic. Thanks.

fix(theme): handle parameters in JSON and XML content types

5a35965

Refs PaloAltoNetworks#603

fly1d had a problem deploying to default October 27, 2026 13:07 — with GitHub Actions Error

fly1d mentioned this pull request Oct 27, 2026

fix(theme): serialize supplied request examples #1678

Merged

sserrata requested changes Oct 28, 2026

View reviewed changes

sserrata mentioned this pull request Oct 28, 2026

Preserve request bodies when selecting form media types #1677

Merged

fix: share request media type handling

bd0b3b7

fly1d had a problem deploying to default October 28, 2026 20:45 — with GitHub Actions Error

fly1d changed the title ~~fix(theme): handle parameters in JSON and XML content types~~ fix: share request media type handling Oct 28, 2026

sserrata requested changes Oct 29, 2026

View reviewed changes

Keep media helpers local and select body mode before headers

a3a0963

fly1d changed the title ~~fix: share request media type handling~~ Normalize request media types without a new plugin dependency Oct 29, 2026

fly1d deployed to default October 29, 2026 18:04 — with GitHub Actions Active

sserrata approved these changes Oct 30, 2026

View reviewed changes

fly1d deployed to preview October 30, 2026 15:55 — with GitHub Actions Active

fly1d deployed to preview October 30, 2026 15:56 — with GitHub Actions Active

Merge form body handling into the media type fix

7238bb2

fly1d requested a deployment to default October 31, 2026 05:15 — with GitHub Actions Waiting

Navigation Menu

Repository navigation

Normalize request media types without a new plugin dependency - #1676

Normalize request media types without a new plugin dependency#1676
fly1d wants to merge 4 commits into
PaloAltoNetworks:mainfrom
fly1d:fix/content-type-parameters

fly1d commented Oct 27, 2026 •

edited

Loading

Uh oh!

sserrata left a comment

Uh oh!

sserrata Oct 28, 2026

Uh oh!

sserrata left a comment

Uh oh!

sserrata Oct 29, 2026

Uh oh!

sserrata Oct 29, 2026

Uh oh!

sserrata Oct 29, 2026

Uh oh!

sserrata Oct 29, 2026

Uh oh!

sserrata left a comment

Uh oh!

github-actions Bot commented Oct 30, 2026

Uh oh!

github-actions Bot commented Oct 30, 2026

Uh oh!

sserrata commented Oct 30, 2026

Uh oh!

This branch is waiting to be deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

fly1d commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sserrata left a comment

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata left a comment

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 30, 2026

Uh oh!

github-actions Bot commented Oct 30, 2026

📸 Visual Diff Report

Uh oh!

sserrata commented Oct 30, 2026

Uh oh!

This branch is waiting to be deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fly1d commented Oct 27, 2026 •

edited

Loading