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

[florianstoll]

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

[sserrata]

Hi @florianstoll, thanks for reporting the issue. Adding a doc ID suffix could be the way to go but I wonder if we could also address this using slug?

For example:

---
id: user
title: "Users"
description: "Users"
custom_edit_url: null
slug: "tags/user"
---

[florianstoll]

Hi @florianstoll, thanks for reporting the issue. Adding a doc ID suffix could be the way to go but I wonder if we could also address this using slug?

For example:

---
id: user
title: "Users"
description: "Users"
custom_edit_url: null
slug: "tags/user"
---

Hi @sserrata, how could we override slug per tag page? Frontmatter?

[sserrata]

Hi @sserrata, how could we override slug per tag page? Frontmatter?

Yes, that would be one way...of course, you'd have to edit each time you re-generate, which may or may not be an issue depending on your setup.

Thinking more broadly, I was contemplating whether or not to just include that in the generated tag frontmatter by default, which would mean that all tag routes would include "tags/" in the path. Could also do the same for info docs, e.g. "info/". Again, I am not decided on it, just floating the idea to see what you and others might think.