fix(theme): serialize supplied request examples by fly1d · Pull Request #1678 · PaloAltoNetworks/docusaurus-openapi-docs

fly1d · 2026-10-27T16:50:44Z

JSON and XML request examples can be skipped for false/0 or reach LiveEditor as non-string values. JSON-looking strings are also handled differently in single and named examples.

Serialize supplied schema, media-type and named values before rendering. Respect string schema types, including nullable OpenAPI 3.1 string types, while retaining pre-encoded JSON objects/arrays for other schemas. Ignore media-type null placeholders and named entries without an inline value. Keep payload summary fields in the payload; only named Example Object summaries render as Markdown. Supplied XML objects and primitives now produce editor text as well.

Generated samples and the legacy fallback keep main's existing truthy checks and serialization, including the existing generated true and quoted "null" defaults. Jest's jsdom, sampler-source mapping and XML JavaScript transform are confined to the new Body test project; the other 13 suites retain their original settings.

Validation on Node 26.5.0, macOS arm64:

yarn test --runInBand: 250 tests, 14 suites and 35 snapshots passed. The 75 mounted component/Redux regressions have 34 failures on the previous PR head and all pass after the fix. Editor and Docusaurus UI shells are substituted; effects, sampler and reducers run normally.
NX_SKIP_NX_CACHE=true yarn build-packages: all three packages built. Changed-file ESLint (--max-warnings 0) and Prettier passed.
25 independent component-to-local-HTTP checks passed, through Body callbacks and real request bytes; the previous head passes 9/25.
An isolated port retaining Normalize request media types without a new plugin dependency #1676 passes both focused suites (94 tests) without built package output. The same 25 HTTP scenarios also pass with vendor JSON/XML types and charset parameters. Normalize request media types without a new plugin dependency #1676 still needs a configuration/adjacent-hunk reconciliation if it merges first; this PR remains based on main.

Full yarn lint was run and exits 2 at the unknown cypress/globals environment in cypress/.eslintrc.js. An untouched main archive with the same dependencies reports the same error. No Cypress or dependency change is included. The CI platform matrix was not run locally.

sserrata

Thanks for the fix. Inline comments cover the main issues. Two more items outside the diff:

XML branch (~L179–200): still uses truthy checks (if (contentTypeExample), if (example)), so 0/false give an empty editor. Non-string named ex.value goes through format(), falls back to the raw object, and crashes LiveEditor — the same crash this PR fixes for JSON.
Lint: please run the full yarn lint (required by AGENTS.md), not only ESLint on changed files.

Items on L154, L157 and L438 can cause regressions and should be fixed before merge.

sserrata · 2026-10-28T15:05:18Z

      contentType?.endsWith("+json")
    ) {
-      if (contentTypeExample) {
+      if (contentTypeExample !== undefined) {


contentTypeExample also holds sampler output. With !== undefined, a bare type: integer / type: boolean schema now prefills the editor and Redux body with 0 / true on load, so "Send" sends a value the user never entered. type: "null" yields the string "null" (quoted), not JSON null. Previously the editor was empty.

sserrata · 2026-10-28T15:05:18Z

        defBody = JSON.stringify(contentTypeExample, null, 2);
      }
-      if (example) {
+      if (example !== undefined) {


An explicit example: null now sets exBody to "null". The if (exampleBody) render branch runs before the named-examples branch, so any examples on the same media type are hidden. Swagger 2 converters often emit example: null. Suggest example != null.

sserrata · 2026-10-28T15:05:18Z

      }
-      if (example) {
+      if (example !== undefined) {
        exBody = JSON.stringify(example, null, 2);


A string example is always stringified, so example: '{"id": 1}' shows as an escaped string. The same value under examples.x.value is treated as pre-encoded and not stringified. The two paths should handle strings the same way.

sserrata · 2026-10-28T15:05:18Z

      }
      if (examples) {
        for (const [key, ex] of Object.entries(examples)) {
          let body = ex.value;


A named example with only externalValue (no value) gives body: undefined, but an entry is still pushed. The result is a tab with a summary and no editor. Suggest skipping entries where ex.value === undefined.

sserrata · 2026-10-28T15:05:18Z

-            JSON.parse(ex.value);
-          } catch (e) {
-            body = JSON.stringify(ex.value, null, 2);
+          if (typeof body === "string") {


"Parses as JSON → already encoded" is ambiguous for string-typed values like "123", "true", "null". With type: string, value: "123" is sent as the number 123. The new "preserves pre-encoded named JSON" tests lock this in. Consider checking the schema type, or only treating strings that parse to objects/arrays as pre-encoded.

Also, JSON.stringify(body, null, 2) is duplicated in both branches. This can be one condition: if (typeof body !== "string" || !isJson(body)).

sserrata · 2026-10-28T15:05:19Z

          {/* @ts-ignore */}
          <TabItem label="Example" value="example">
-            {example.summary && <Markdown>{example.summary}</Markdown>}
+            {example?.summary && <Markdown>{example.summary}</Markdown>}


Pre-existing, but this line is touched: the media-type example is the payload itself, not an Example Object. A payload with a summary field is rendered as Markdown here, and an object-valued summary throws "Objects are not valid as a React child". This line should be removed rather than made optional-chained.

sserrata · 2026-10-28T15:05:19Z


 module.exports = {
-  preset: "ts-jest",
+  preset: "ts-jest/presets/js-with-ts",


This changes Jest config for every suite to support one test file: js-with-ts + allowJs now transforms all .js under the roots, and theme tests resolve the plugin's src instead of the built lib. The createSchemaExample mapping is also duplicated in tsconfig.paths and moduleNameMapper. Since this matches #1676, whichever merges second will conflict. Consider landing the Jest setup once, separately.

sserrata

Requesting changes per the review above. Please fix the L154, L157 and L438 items (regression risk) and the XML branch before merge.

sserrata

Thanks for the updates. All review items are addressed. yarn test passes locally (250/250).

github-actions · 2026-10-28T19:20:49Z

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

https://docusaurus-openapi-36b86--pr1678-76ai42ju.web.app

_{(expires Wed, 04 Nov 2026 19:20:41 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

github-actions · 2026-10-28T19:25:35Z

📸 Visual Diff Report

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

Total	✅ Match	❌ Diff	⏭ Skip
228	228	0	0

Preview: https://docusaurus-openapi-36b86--pr1678-76ai42ju.web.app
Diff images: https://docusaurus-openapi-36b86--pr1678-diffs-uixzuot4.web.app/
Full HTML report: download from run artifacts

✅ No visual regressions detected.

_{Updated at 2026-10-28T19:25:34.726Z · run 40737471662}

fix(theme): preserve primitive JSON request examples

210eb8b

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

sserrata reviewed Oct 28, 2026

View reviewed changes

sserrata requested changes Oct 28, 2026

View reviewed changes

fix(theme): serialize supplied request examples

f23a83b

fly1d deployed to default October 28, 2026 17:37 — with GitHub Actions Active

fly1d changed the title ~~fix(theme): preserve primitive JSON request examples~~ fix(theme): serialize supplied request examples Oct 28, 2026

sserrata approved these changes Oct 28, 2026

View reviewed changes

fly1d had a problem deploying to preview October 28, 2026 19:12 — with GitHub Actions Failure

fly1d deployed to preview October 28, 2026 19:20 — with GitHub Actions Active

sserrata merged commit 76c7c7e into PaloAltoNetworks:main Oct 28, 2026
16 of 18 checks passed

This was referenced Oct 28, 2026

feat(theme): add generateExamples option #1656

Open

Normalize request media types without a new plugin dependency #1676

Open

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 Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

sserrata Oct 28, 2026

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 left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 28, 2026

Uh oh!

github-actions Bot commented Oct 28, 2026

📸 Visual Diff Report

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fly1d commented Oct 27, 2026 •

edited

Loading