Schemas should not be added to all (or any?) x-tagGroups groups when showSchemas: true

[ElliotFriend]

Describe the bug

All defined schemas in an OpenAPI doc are displayed as a "Schemas" sub-category under each tagGroup category.

Expected behavior

I'm not precisely sure what I expected to happen, but I could see two options feeling "predictable," from my point of view:

1. An additional "Schemas" category is displayed as a sibling to the defined tagGroup categories, containing all the defined schemas from the API doc.
2. A "Schemas" sub-category displayed as a child under every tagGroup category, but only containing the relevant defined schemas to that particular tagGroup category.

I think I'd prefer the first option, myself. Maybe it's also a bit easier to implement?

Current behavior

I have a plugin instance that is listing the x-tagGroups groups properly (after a little work, see this comment), with two tagGroups to speak of: "Resources" and "Aggregations." I also have showSchemas set to true in the plugin config.

The Schemas category then shows up in both of the tagGroups, with all defined schemas in the whole OpenAPI doc showing in both schemas categories.

Possible solution

In sidebars/index.ts, maybe the logic for creating the "Schemas" category could be move out of the groupByTags function, and into the generateSidebarSlice function. Then it could be added on to sidebarSlice just before returning (whether it was grouped by tag or tagGroup). I suppose

Steps to reproduce

I don't (at the moment) have a live repro, but I can create one. Here's the relevant config:

[
  "docusaurus-plugin-openapi-docs",
  {
   id: "openapi",
   docsPluginId: "network",
   config: {
     horizon: {
       specPath: "openapi/horizon/bundled.yml", // Path to designated spec file
       outputDir: "network/horizon/api-reference", // Output directory for generated .mdx docs
       sidebarOptions: {
         groupPathsBy: "tagGroup",
         categoryLinkSource: 'auto',
       },
       showSchemas: true,
    } satisfies OpenApiPlugin.Options,
  },
],

My OpenAPI specfile has two tagGroups defined: "Resources" and "Aggregations."

Screenshots

Context

We have some (quite old) customizations to how sidebars are generated for the OpenAPI plugin, and I'm trying to "regular-ize" and clean up our usage, while also making sure our specfile is as polished as possible. We could definitely use the x-tagGroups extension to do away with some of the cumbersome, old code. Providing the "Schemas" category would help in this regard, but not in the current way it's generating/placing that category.

Your Environment

• Version used: v3.0.0-beta.10
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): node.js 20.13.1 running on nginx
• Operating System and version (desktop or mobile): Desktop
• Link to your project: https://github.com/stellar/stellar-docs

[ElliotFriend]

Perhaps it's only tangentially related to this particular issue, but I've just discovered the redocly extension x-tags for schema objects. The point of x-tags is pretty close to "option 2" in my original issue description.

I don't know what it takes to "support <blank> extension," in the plugin, but maybe that's a way to approach it.

[sserrata]

@ElliotFriend is this issue resolved since #837 was merged?

[ElliotFriend]

Hey, thanks for asking! In #837, I didn't actually actually do anything to resolve the "schemas added to every tagGroup" thing. I wasn't exactly sure how to handle it. The x-tags feature definitely does suffice as a way to avoid the problem (for me, at least), but I think x-tagGroups and showSchemas is still incompatible.

I can work on getting a proper bug fix ready this week, if you'd like.

[sserrata]

Thanks @ElliotFriend, that would be great!

[ElliotFriend]

Just made #851 to address this.

Edit: Added a v3 version, too #852