PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

When configured for versioning, I can't use an outputDir outside the docs plugin's path

Open
#913 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

Describe the bug

If my configured versions in the docusaurus-plugin-openapi-docs plugin instance specify an outputDir that does not contain the path value from the @docusaurus/plugin-content-docs plugin instance, then gen-api-docs:version will fail to build.

Expected behavior

For the docusaurus-plugin-openapi-docs plugin to generate the versioned MDX files at whatever location I have configured. Even if it's outside the docs path.

Current behavior

I think the docusaurus-plugin-openapi-docs plugin assumes that the outputDir for a given version will always be contained within the path value for the docs plugin.

Trying to generate the versioned MDX files like yarn docusaurus gen-api-docs:version -p ap-apis ap_platform:2.8.4 results in an error similar to:

[ERROR] TypeError: Cannot read properties of undefined (reading 'replace')
    at /Users/elliotvoris/Dev/docs/stellar/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:256:30
    at Array.map (<anonymous>)
    at generateApiDocs (/Users/elliotvoris/Dev/docs/stellar/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:225:17)
    at async Command.<anonymous> (/Users/elliotvoris/Dev/docs/stellar/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:535:11)

(Note: those line numbers are probably wrong, I had added some console.log() statements in that file for troubleshooting)

Possible solution

One possible fix might be as simple as modifying the plugin's index.ts file like this:

          if (docRouteBasePath) {
-           infoBasePath = `${docRouteBasePath}/${outputDir
-             .split(docPath!)[1]
-             .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+           infoBasePath = outputDir.indexOf(docPath) > -1
+             ? `${docRouteBasePath}/${outputDir
+                 .split(docPath)[1]
+                 replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "")
+             : infoBasePath;
          }

If that's a fitting fix, I'm more than happy to create a PR for it. (Here's a patch I'm using temporarily to fix it and it's working pretty well I think [ignore the other stuff in the patch file, that's an unrelated issue that I'll someday make a PR for lol])

Steps to reproduce

Here's the steps I remember doing:

  1. Create a new version with the docusaurus docs plugin using yarn docusaurus docs:version:ap 2.8.4 (ap is the id of the docs plugin instance)

  2. Add versions to the openapi plugin so it can re-generate the "old" versions when required. Including the plugin-content-docs instance here, for (hopefully) added clarity.

[
    "docusaurus-plugin-openapi-docs",
    {
        id: "ap-apis",
        docsPluginId: 'ap',
        config: {
            ap_platform: {
                specPath: "openapi/anchor-platform/bundled-platform.yaml",
                outputDir: "platforms/anchor-platform/api-reference/platform/transactions",
                hideSendButton: true,
                template: "src/template.mustache",
                version: "3.0.0",
                label: "v3.0.0",
                baseUrl: '/platforms/anchor-platform/next/api-reference/platform/transactions',
                versions: {
                    "2.8.4": {
                        specPath: "openapi/anchor-platform/versions/platform-2.8.4.yaml",
                        outputDir: "ap_versioned_docs/version-2.8.4/api-reference/platform/transactions",
                        label: "v2.8.4",
                        baseUrl: "/platforms/anchor-platform/api-reference/platform/transactions"
                    }
                }
            } satisfies OpenApiPlugin.Options,
        }
    }
],
[
    "@docusaurus/plugin-content-docs",
    {
        id: "ap",
        path: "platforms/anchor-platform",
        routeBasePath: "/platforms/anchor-platform",
        docItemComponent: "@theme/ApiItem",
        sidebarPath: "config/anchorPlatform.sidebar.ts",
        editUrl: "https://github.com/stellar/stellar-docs/tree/main",
        exclude: ['**/component/**', '**/README.md'],
        showLastUpdateTime: true,
        showLastUpdateAuthor: true,
    },
],
  1. Attempt to change and re-generate the MDX files with yarn docusaurus gen-api-docs:version -p ap-apis ap_platform:2.8.4
  2. Error as described above.

Context

My use-case is a little complicated here, and likely atypical. We're configuring a new instance of @docusaurus/plugin-content-docs (there are others) to work with a new instance of docusaurus-plugin-openapi-docs (there are also others). We want to setup versioning for just a specific part of our docs site, hence the multi-instance stuff.

We want to version all of the docs that are managed by this @docusaurus/plugin-content-docs instance. So, I've used the "regular" docusaurus method to make a new version. When configuring the docusaurus-plugin-openapi-docs instance, I'm adding versions so that I could update the "old" versions if it ever becomes necessary.

Maybe this isn't the "best" or "typical" way of accomplishing this? Essentially we're looking to version everything under a /certain/url/path without versioning anything else. Is there already any established precedent for this kind of use-case?

The relevant config in the working branch can be found here, for those curious enough to dive in.

Your Environment

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in packages/docusaurus-plugin-openapi-docs/src/index.ts around the versioned output path handling described in the issue. Run yarn docusaurus gen-api-docs:version -p ap-apis ap_platform:2.8.4 with an outputDir outside the docs plugin path and trace the failing path calculation. Done means versioned MDX files are generated at the configured outputDir without the undefined-property error.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, openapi, typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.