PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

duplicate spec outputs causing conflicts

Open
#1,101 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.