[Multi-Spec Umbrella] Support Nested Sidebar Navigation for Multiple API Specifications

I’d like to potentially use this library to render many OpenAPI specs within a single Docusaurus site.

The current implementation only supports top level navigation (with single level drop downs) for multiple OpenAPI specs. This is a limitation of docusaurus itself. If I wanted to render hundreds of specs, it would not scale very well - there’s only so much real estate in the top nav.

A viable solution may be to use multiple top-level navs with drop-downs and see how far we can get until https://github.com/facebook/docusaurus/issues/5938 is addressed. At a certain point, though, top level navigation itself doesn’t scale even with dropdowns.

Feature Request:

Allow multiple OpenAPI specs to be rendered within the Sidebar of a single route base path.

The current implementation groups operations by tag similar to the Swagger UI within the sidebar.

In order to support N specifications we should be able to render each spec as a category, or, an arbitrary grouping of specs as a category. This will scale better because vertical navigation is less constrained.

Current State

"Logo" "Tutorial" "Auth" "API" "Issue 21" "COS" "YAML" "Blog"
---
pet
	Recursive
	Find pet by ID

Target State

"Logo" "Tutorial" "Auth" "API Reference" "Blog"
---
Group A // specification grouping
	Pet Store // specification description
		pet // operation label/group
			Recursive // operation
			Find pet by ID // operation
	Issue 21 // server
		Missing Summary
Group B
	COS
		Authentication
		Generating an IAM Token
	YAML

A configuration could look something like:

{
  themeConfig:
    /** @type {import('docusaurus-preset-openapi').ThemeConfig} */
    ({
      navbar: {
        // ...
        items: [
          { to: "/auth", label: "Auth", position: "left" },
          {
            label: "API Reference",
            activeBasePath: "api",
            // only relevant at top level
            position: "left",
          },
          // ...
        ],
      },
    }),
  plugins: [
    // can maintain existing functionality
    [
      "docusaurus-plugin-openapi",
      {
        id: "authentication",
        // path to openapi spec
        path: "examples/auth.json",
        // navigation subpath - ties the plugin to the routing
        routeBasePath: "auth",
      },
    ],
    [
      "docusaurus-plugin-openapi",
      {
        // id: null - no need for id for a category
        // navigation subpath - ties the plugin to the routing
        routeBasePath: "api",
        items: [
          {
            label: "Group A",
            routeBasePath: "a",
            items: [
              {
                id: "pet-store",
                label: "Pet Store",
                // becomes api/a/pet-store/[operation]
                // http://localhost:3000/api/a/pet-store/recursive
                routeBasePath: "pet-store",
                // path to openapi spec
                path: "examples/pet-store.json",
              },
              {
                id: "issue21",
                label: "Issue 21",
                routeBasePath: "issue-21",
                path: "examples/openapi-issue-21.json",
              },
            ],
          },
          {
            label: "Group B",
            routeBasePath: "b",
            items: [
              {
                id: "cos",
                label: "COS",
                routeBasePath: "cos",
                path: "examples/cos.json",
              },
              {
                id: "yaml",
                label: "YAML",
                // http://localhost:3000/api/b/yaml/hello-world
                routeBasePath: "yaml",
                path: "examples/yaml.json",
              },
            ],
          },
        ],
      },
    ],
  ],
};

TODO:

• Add recursive folder structure reading & labeling support (#107)
• #133
• #134
• #135
• #136
• #137

[bourdakos1]

@blugavere Can we update the description of this issue to include a todo list to track tasks we still need to complete?

What I can think of off the top of my head:

• #133
• #134
• #135
• #136
• #137

[bourdakos1]

I’m good with having a specific spec name for the “I want to render the swagger spec the folder in which it resides with custom mdx” case