PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs
When configured for versioning, I can't use an outputDir outside the docs plugin's path
Nobody has claimed this yet.
- 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:
-
Create a new version with the docusaurus docs plugin using
yarn docusaurus docs:version:ap 2.8.4(apis the id of the docs plugin instance) -
Add versions to the openapi plugin so it can re-generate the "old" versions when required. Including the
plugin-content-docsinstance 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,
},
],
- Attempt to change and re-generate the MDX files with
yarn docusaurus gen-api-docs:version -p ap-apis ap_platform:2.8.4 - 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
- Version used: 3.0.1
- Environment name and version: node.js v20
- Operating System and version: macOS 14.5
- Link to your project: The feature branch is located here https://github.com/stellar/stellar-docs/tree/ap/versioning-setup
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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