[V3] Fix tagGroup display when showSchemas is configured (#852)

* Rearrange Schemas category from each tagGroup category

This commit takes the first tagGroup category's Schema category,
adds it to the very end of the sidebarSlice, and deletes the Schema
category from all the (now sibling) tagGroup categories.

Closes #836

* add a schema object to the Restaurant specfile

* show schemas in the restaurant demo API

* add documentation to sidebars.md

Author: ElliotFriend

demo/docs/sidebars.mdx

@@ -57,6 +57,8 @@ The OpenAPI docs plugin provides out-of-the-box support for grouping paths by "t
 What this means is that the plugin will automatically generate a sidebar slice using the first path group as the "group by" value and the path itself as one of the `tags` under that category.
 Use `x-tagGroups` to group tags in the [Reference](https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/) docs navigation sidebar. Add it to the root OpenAPI object.
 
+If `x-tagGroups` is used for grouping API paths, and you've also configured `showSchemas: true` for your OpenAPI Docs plugin, an additional "sibling" category labelled `Schemas` will be created and placed at the end of sidebar, after all the `tagGroups` categories.
+
 ### Category Links
 
 Docusaurus now supports the ability to designate or customize what page gets displayed when a category is clicked.

demo/docusaurus.config.ts

@@ -266,6 +266,7 @@ const config: Config = {
             sidebarOptions: {
               groupPathsBy: "tagGroup",
             },
+            showSchemas: true,
           } satisfies OpenApiPlugin.Options,
         } satisfies Plugin.PluginOptions,
       },

demo/examples/food/restaurant/openapi.yaml

@@ -43,6 +43,17 @@ paths:
         200:
           description: OK
 
+components:
+  schemas:
+    Payment:
+      type: object
+      properties:
+        amount:
+          type: number
+        method:
+          type: string
+          enum: [cash, card, check]
+
 tags:
   - name: tag1
     description: Everything about your restaurant

packages/docusaurus-plugin-openapi-docs/src/sidebars/index.ts

@@ -267,6 +267,7 @@ export default function generateSidebarSlice(
   let sidebarSlice: ProcessedSidebar = [];
 
   if (sidebarOptions.groupPathsBy === "tagGroup") {
+    let schemasGroup: ProcessedSidebar = [];
     tagGroups?.forEach((tagGroup) => {
       //filter tags only included in group
       const filteredTags: TagObject[] = [];
@@ -288,10 +289,24 @@ export default function generateSidebarSlice(
           [filteredTags],
           docPath
         ),
-      } as ProcessedSidebarItem;
+      };
 
-      sidebarSlice.push(groupCategory);
+      if (options.showSchemas) {
+        // For the first tagGroup, save the generated "Schemas" category for later.
+        if (schemasGroup.length === 0) {
+          schemasGroup = groupCategory.items?.filter(
+            (item) => item.type === "category" && item.label === "Schemas"
+          );
+        }
+        // Remove the "Schemas" category from every `groupCategory`.
+        groupCategory.items = groupCategory.items.filter((item) =>
+          "label" in item ? item.label !== "Schemas" : true
+        );
+      }
+      sidebarSlice.push(groupCategory as ProcessedSidebarItem);
     });
+    // Add `schemasGroup` to the end of the sidebar.
+    sidebarSlice.push(...schemasGroup);
   } else if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
   }