fix: skip vendor extensions at the path level(#891)

[nicumicle]

Description

The plugin fails when the OpenAPI spec file contains vendor extensions at the path level (e.g. x-* fields directly under a path object). This results in a runtime error during the build process.

Motivation and Context

OpenAPI allows vendor extensions (x-*) at almost any level of the specification, including the path level. However, the current implementation assumes all path-level properties conform to expected schema objects and attempts to process vendor extensions as structured objects.

This leads to a crash when a primitive value (e.g. string or boolean) is encountered, as the code tries to assign properties like description to it.

This change ensures that vendor extensions at the path level are safely ignored or handled correctly, preventing the build from failing.

Issue: #891

How Has This Been Tested?

I modified the petstore.yaml example to include vendor extensions at the path level:

paths:
    /pet:
       x-custom-string: hello
       x-custom-bool: true
       parameters:
                ....
       post:
                .....

Before the fix

Running:

yarn build

Resulted in:

[ERROR] TypeError: Cannot create property 'description' on string 'hello'

After the fix

Running:

yarn build

Produces:

....
Successfully created "docs/petstore_versioned/versions.json"
[INFO] [en] Creating an optimized production build...
● Client ██████████████████████████████████████████████████ (100%) emitting after emit                                                               
● Server ██████████████████████████████████████████████████ (100%) emitting after emit  

The build now completes successfully without errors.

Screenshots (if appropriate)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[sserrata]

Thanks for the fix! Confirmed the crash and that this resolves it. A few suggestions before merging:

1. Prefer an HTTP-method allowlist over an x-* blocklist. The OpenAPI 3.x spec defines exactly 8 valid operation keys, so any other unexpected non-x- key (typo, third-party tooling, future spec addition) would still crash. Something like:

   const HTTP_METHODS = new Set(["get","put","post","delete","options","head","patch","trace"]);
   if (!HTTP_METHODS.has(method.toLowerCase())) continue;

   This makes the guard spec-correct and self-documenting (the comment becomes unnecessary).

2. Add a unit test under packages/docusaurus-plugin-openapi-docs/src/openapi/__tests__/ that constructs a path with vendor extensions and asserts createItems doesn't throw. The petstore demo edit is a nice smoke test but won't catch a future regression on its own.

3. Minor: drop the stray blank line between the comment and continue;.

Happy to merge once those are addressed (or as-is if you'd rather ship the fix now and file a follow-up).

[github-actions]

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

https://docusaurus-openapi-36b86--pr1440-binjd7cp.web.app

_{(expires Mon, 11 May 2026 14:38:41 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}