Resolve parameters embedded in path segments by fly1d · Pull Request #1669 · PaloAltoNetworks/docusaurus-openapi-docs

fly1d · 2026-10-27T10:19:21Z

Refs #621. The binding fix in #1311 does not resolve parameters embedded in a segment, such as /records/{id}:publish.

Pass the original api.path explicitly to request and snippet builders. Use the authored path for embedded parameters and literal collection tokens; ordinary standalone parameters retain the SDK's :name representation and bindings. Inserted /, ? and # are encoded. Bindings are cleared only on the materialized clone, and the original request remains unchanged. Unclosed parameters warn and retain the converted path; adjacent extra braces keep their literal text.

Include the main-branch changes through #1677, preserving its body-error handling in both consumers. An explicit string annotation fixes type inference in the new upstream Jest project; the emitted builder JavaScript is unchanged by that annotation.

Validation on Node 26.5.0/macOS: full yarn test passes 353 tests across 16 suites. All three packages build without cache; strict changed-file ESLint, Prettier and diff checks pass. The existing path-parameter fixtures remain unchanged.

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#621

sserrata

Thanks. The embedded path parameter cases are handled, but the internal variable names appear in user-visible output. Please address the inline items. Consider doing this in the plugin's Postman conversion or building the path from api.path, so that the theme does not need to undo the converter's {{name}} format.

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

+    if (!substituted || resolved === "") return resolved;
+
+    // Bind once so a leading colon in the value cannot be interpreted again.
+    let key = `__openapi_path_${index}`;


Every resolved embedded segment becomes :__openapi_path_N. Raw URL output (getRaw(), toString(true), toJSON(), code snippets) then shows /records/:__openapi_path_1 and not /records/9527:publish. Use the internal variable only when the resolved value starts with :.

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

  );
+  postman.url.path = postman.url.path?.map((segment, index) => {
+    let substituted = false;
+    const resolved = segment.replace(/\{\{([^{}]+)\}\}/g, (token, name) => {


The regex replaces every {{name}} token whose name matches a path param. A literal collection-variable token is also replaced, and a converter change can stop the fix with no error.

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

+
+    // Bind once so a leading colon in the value cannot be interpreted again.
+    let key = `__openapi_path_${index}`;
+    while (postman.url.variables.has(key)) key += "_";


The collision check looks only at url.variables. A native :__openapi_path_N segment that has no variable gets the injected value. Use a key that cannot collide.

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

+    let substituted = false;
+    const resolved = segment.replace(/\{\{([^{}]+)\}\}/g, (token, name) => {
+      const value = values.get(name);
+      if (typeof value !== "string") return token;


Embedded params with no value stay as {{id}}, but native params fall back to the example. The URL and the snippets then show both formats.

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

+      substituted = true;
+      return value;
+    });
+    if (!substituted || resolved === "") return resolved;


An empty value in a middle segment gives /records//items. The test covers only the trailing segment.

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

 * ========================================================================== */

+// eslint-disable-next-line import/no-extraneous-dependencies
+import { processOpenapiFile } from "docusaurus-plugin-openapi-docs/src/openapi/openapi";


The theme test now imports plugin source at runtime and uses toBeInstanceOf(sdk.Request) across two package copies. It runs a full conversion for each of about 21 cases. Use inline sdk.Request fixtures, or cache the conversion by template.

sserrata

Thanks for the update. The internal variable names are now gone. One behavior change must be reverted before merge:

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

+        fallback !== null &&
+        String(fallback) !== ""
+        ? String(fallback)
+        : `{{${name}}}`;


Behavior change for all endpoints: pathTemplate is now always passed, so an unfilled path param shows as {{petId}} in place of :petId. This happens in snippets and in the sent URL (/pets/%7B%7BpetId%7D%7D). It affects every existing site. Please keep the earlier :name output for unfilled params, and change only the embedded-parameter case.

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

+      }
+      const value = values.get(name);
+      if (value !== undefined && value !== null && String(value) !== "") {
+        return String(value);


The value goes into the segment without encoding. With /records/{id}:publish and id = a?b, the path becomes /records/a and the query becomes b:publish. A # moves the rest into the fragment. Encode reserved characters (/, ?, #) in the value.

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

+  postman.url.path = path.split("/").map((segment) =>
+    segment.replace(/\{([^{}]+)\}/g, (token, name, offset) => {
+      // Only OpenAPI placeholders are path parameters; collection tokens are literal.
+      if (


The adjacent-brace check leaves {id} unresolved in /a/{{id} or /a/{id}}, and the user gets no warning.

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

+
+  if (pathTemplate === undefined) return;
+
+  const values = new Map(


When pathTemplate is set, the variables are assimilated, read back and cleared, and fallbackValues (line 113) is built even when it is not used. Build one value map and resolve from it.

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

    request ??
    new sdk.Request({ url: "http://example.com/pets/:petId", method: "GET" });
  return buildPostmanRequest(postman, {
+    pathTemplate: request && requestTemplates.get(request),


The tests get pathTemplate through a hidden WeakMap. Pass it explicitly in the options so that the dependency is visible. The & { pathTemplate?: string } on line 15 is also not necessary.

sserrata

Thanks. All review items are addressed, and unfilled path params keep the earlier :name output.

github-actions · 2026-10-30T15:55:48Z

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

https://docusaurus-openapi-36b86--pr1669-cnv47t9r.web.app

_{(expires Mon, 09 Nov 2026 18:50:39 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

github-actions · 2026-10-30T16:02:22Z

📸 Visual Diff Report

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

Total	✅ Match	❌ Diff	⏭ Skip
228	228	0	0

Preview: https://docusaurus-openapi-36b86--pr1669-cnv47t9r.web.app
Diff images: https://docusaurus-openapi-36b86--pr1669-diffs-pufrl2lm.web.app/
Full HTML report: download from run artifacts

✅ No visual regressions detected.

_{Updated at 2026-11-02T18:57:28.213Z · run 41172014882}

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

This PR now conflicts with main after #1677 merged (CodeSnippets/index.tsx, Request/index.tsx). Please rebase onto main. Thanks.

Keep both the scalar query serialization fix and the pathTemplate handling from PaloAltoNetworks#1669. setPathParams now takes normalized path params plus an optional path template, and the call site passes normalizeParams(pathParams) and pathTemplate. Also clear the two import/order warnings with eslint --fix.

fix(theme): resolve embedded path parameters

7dbedcd

Refs PaloAltoNetworks#621

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

sserrata requested changes Oct 28, 2026

View reviewed changes

fix: materialize OpenAPI paths without SDK aliases

c653e6e

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

sserrata requested changes Oct 29, 2026

View reviewed changes

Preserve native bindings for standalone path parameters

acbaf0e

fly1d changed the title ~~fix(theme): resolve embedded path parameters~~ Resolve parameters embedded in path segments Oct 29, 2026

fly1d deployed to default October 29, 2026 18:02 — 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

Merge main into the custom verb parameter fix

1b8a7d2

fly1d deployed to default October 31, 2026 05:17 — with GitHub Actions Active

fly1d deployed to preview November 2, 2026 18:50 — with GitHub Actions Active

sserrata merged commit da2980f into PaloAltoNetworks:main Nov 2, 2026
11 of 12 checks passed

sserrata mentioned this pull request Nov 2, 2026

fix(explorer): serialize scalar query parameter defaults #1655

Open

fly1d mentioned this pull request Nov 2, 2026

Preserve Markdown code while cleaning descriptions #1607

Open


		if (pathTemplate === undefined) return;

		const values = new Map(

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sserrata left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📸 Visual Diff Report

Uh oh!

sserrata commented Oct 30, 2026

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

github-actions Bot commented Oct 30, 2026 •

edited

Loading

github-actions Bot commented Oct 30, 2026 •

edited

Loading