PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs
duplicate spec outputs causing conflicts
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.1k
- Forks
- 315
- Avg merge
- 7d 5h
- Merged PRs (30d)
- 7
Description
Describe the problem
Context
I'm currently configuring this plugin in a documentation repository that is structured to generate internal and client documentation. It contains multiple spec outputs for internal and external (client) documentation too. The swagger specs are being auto-generated under /generated/ swagger-internal/ and /generated/swagger-external/ respectively (they don't exist statically in this doc repository). Some internal and external specs share the same APIs. For instance, /generated/swagger-internal/abc.json shares the exact same APIs as /generated/swagger-external/abc.json except for one API (only available internally), which is the reason for generating two different outputs.
What is happening
When I add the categoryLinkSource as tag in both internal and external configurations, the client build builds successfully but the internal build fails with:
Error: Docusaurus static site generation failed for 4 paths:
[INFO] [npm|docusaurus] - "/docs/client/abc/api/endpoints/api-1"
[INFO] [npm|docusaurus] - "/docs/client/abc/api/endpoints/api-2"
[INFO] [npm|docusaurus] - "/docs/client/abc/api/endpoints/api-3"
[INFO] [npm|docusaurus] - "/docs/client/abc/api/endpoints/api-4"
These are the paths to the categories of the APIs shared between /generated/swagger-internal/abc.json and /generated/swagger-external/abc.json.
I've tried using patches to change tags and operationId in one of the specs to avoid overlaps, but the issue persists. Does anyone have an idea what could be causing this? Even if I only add the categoryLinkSource to the client documentation, the internal documentation build fails.
Without this property, the documentation builds successfully for both outputs.
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
Reproduce the issue with the internal and external configurations and the generated/swagger-internal/abc.json and generated/swagger-external/abc.json outputs. Start with the categoryLinkSource configuration and the failing internal build paths under /docs/client/abc/api/endpoints/. Done means both documentation builds succeed when categoryLinkSource is enabled for the relevant outputs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100