PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

Duplicate routes and wrong page if tagname and operationid have the same name

Open
#1,110 6 comments 1 reaction 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 the OpenAPI contains a tag which has the same name as an operationid in the same file and the tag is added to the resource the tag page (xxx.tag.mdx) is loading the resource instead of the tag page and there are warnings of duplicate routes.
The api page has the same doc id as the resource page.

Expected behavior

If you click on the tag or resource page it should open regardless of any name conflict. There should be no name dependency between resource and tag names.

Current behavior

If you click on the tag page with generated-index it loads the resource page instead of the tag page. Child resource page with the same name is working fine because it overrides the tag route.

Possible solution

The tag page should get a non conflicting doc id (e.g. prefix tag_xxx) that makes it possible to open the tag or child resource page. The sidebar must also be aware of this new name schema.

Steps to reproduce

  1. Create OpenAPI with a resource and operationid e.g. users
  2. Add global and local tag to the resource with the same name e.g. users
  3. Regenerate all docs (no warning)
  4. Build docusaurus (warning duplicate routes found should appear)
    --> Attempting to create page at /....../tagname but a page already exists at this route.
  5. Try to open generated resource page (ok)
  6. Try to open generated tag page (it opens the resource page)

Context

There is currently no solution because the OpenAPI spec does not contain any constraints on tag names. Ignoring the warnings at the moment and communicating the constraint is the only way to deal with that.

Your Environment

  • Version used: docusaurus-plugin-openapi-docs 4.3.0 + docusaurus core 3.6.3
  • Environment name and version: Firefox
  • Operating System and version (desktop or mobile): Desktop

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 by reproducing the conflict with an OpenAPI tag and operationId both named users, then run the Docusaurus build and inspect the generated-index route behavior and duplicate-route warning. The work is done when tag and resource pages both open independently, generated tag IDs no longer conflict, and the sidebar follows the new naming scheme.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
documentation, web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.