[Multi-Spec Umbrella] Support Nested Sidebar Navigation for Multiple API Specifications
See original GitHub issueI’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:
Issue Analytics
- State:
- Created 2 years ago
- Reactions:2
- Comments:11 (11 by maintainers)
@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:
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