Group browser paths by tag

[cbreit]

Is your feature request related to a problem?

In a bigger API, some sub-paths might be similar, e.g.

• /my-api-endpoint/user/get-by-id
• /my-api-endpoint/blob/get-by-id

But the OpenApi-Generator creates two paths which are exactly the same:

• /my-api-docs/get-by-id for 'Users'
• /my-api-docs/get-by-id for 'Blobs'

When clicking one of the sidebar items in Docusaurus, both items in the sidebar expand and just the first one is shown; the second is inaccessible. Maybe this is also partly a bug report, as paths to different items with the same URL can be generated.

To reproduce see: https://github.com/cbreit/docusaurus-openapi-docs/commit/459290b4213815df0f077c8643b4f88552d390d7 --> "Find a pet by ID" shows up twice; clicking it opens both entries in "Pets" and "Petstore orders"

Describe the solution you'd like

Create folders on disk matching the groups/tags, place the .mdx files in there and add the group to the browser path to allow similar sub-paths among different groups. I expected 'groupPathsBy' with 'tag' in the sidebarOptions to do exactly that.

If two (ore more) entries with the same path are generated, raise an error.

Additional context

We temporarily renamed every single entry that was similar, but this led to very long path descriptions (like: "Find a single 'Blob' entity with the given id" instead of "Find by ID" in the blobs group.

• /find-a-single-blob-entity-with-the-given-id vs.
• /blobs/find-by-id

Think version 2 is much better readable.

[welcome-to-palo-alto-networks[bot]]

:tada: Thanks for opening your first issue here! Welcome to the community!

[sserrata]

Hi @cbreit thanks for opening this issue. The plugin uses the operationId or summary to determine the file name and doc ID. That said, OpenAPI recommends globally unique operationId for paths in a given spec.