Include global tags and tag docs only if referenced by operation (#340)

Author: sserrata

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

@@ -16,6 +16,7 @@ import fs from "fs-extra";
 import cloneDeep from "lodash/cloneDeep";
 import kebabCase from "lodash/kebabCase";
 import unionBy from "lodash/unionBy";
+import uniq from "lodash/uniq";
 
 import { isURL } from "../index";
 import {
@@ -85,41 +86,6 @@ function createItems(
   let items: PartialPage<ApiMetadata>[] = [];
   const infoId = kebabCase(openapiData.info.title);
 
-  if (sidebarOptions?.categoryLinkSource === "tag") {
-    // Only create an tag pages if categoryLinkSource set to tag.
-    const tags: TagObject[] = openapiData.tags ?? [];
-    // eslint-disable-next-line array-callback-return
-    tags
-      .filter((tag) => !tag.description?.includes("SchemaDefinition"))
-      // eslint-disable-next-line array-callback-return
-      .map((tag) => {
-        const description = getTagDisplayName(
-          tag.name!,
-          openapiData.tags ?? []
-        );
-        const tagId = kebabCase(tag.name);
-        const splitDescription = description.match(/[^\r\n]+/g);
-        const tagPage: PartialPage<TagPageMetadata> = {
-          type: "tag",
-          id: tagId,
-          unversionedId: tagId,
-          title: description ?? "",
-          description: description ?? "",
-          frontMatter: {
-            description: splitDescription
-              ? splitDescription[0]
-                  .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                  .replace(/\s+$/, "")
-              : "",
-          },
-          tag: {
-            ...tag,
-          },
-        };
-        items.push(tagPage);
-      });
-  }
-
   if (openapiData.info.description) {
     // Only create an info page if we have a description.
     const infoDescription = openapiData.info?.description;
@@ -270,6 +236,52 @@ function createItems(
     }
   }
 
+  if (sidebarOptions?.categoryLinkSource === "tag") {
+    // Get global tags
+    const tags: TagObject[] = openapiData.tags ?? [];
+
+    // Get operation tags
+    const apiItems = items.filter((item) => {
+      return item.type === "api";
+    }) as ApiPageMetadata[];
+    const operationTags = uniq(
+      apiItems
+        .flatMap((item) => item.api.tags)
+        .filter((item): item is string => !!item)
+    );
+
+    // eslint-disable-next-line array-callback-return
+    tags
+      .filter((tag) => operationTags.includes(tag.name!)) // include only tags referenced by operation
+      // eslint-disable-next-line array-callback-return
+      .map((tag) => {
+        const description = getTagDisplayName(
+          tag.name!,
+          openapiData.tags ?? []
+        );
+        const tagId = kebabCase(tag.name);
+        const splitDescription = description.match(/[^\r\n]+/g);
+        const tagPage: PartialPage<TagPageMetadata> = {
+          type: "tag",
+          id: tagId,
+          unversionedId: tagId,
+          title: description ?? "",
+          description: description ?? "",
+          frontMatter: {
+            description: splitDescription
+              ? splitDescription[0]
+                  .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                  .replace(/\s+$/, "")
+              : "",
+          },
+          tag: {
+            ...tag,
+          },
+        };
+        items.push(tagPage);
+      });
+  }
+
   return items as ApiMetadata[];
 }
 

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

@@ -68,9 +68,13 @@ function groupByTags(
   );
 
   // Combine globally defined tags with operation tags
+  // Only include global tag if referenced in operation tags
   let apiTags: string[] = [];
   tags.flat().forEach((tag) => {
-    apiTags.push(tag.name!);
+    // Should we also check x-displayName?
+    if (operationTags.includes(tag.name!)) {
+      apiTags.push(tag.name!);
+    }
   });
   apiTags = uniq(apiTags.concat(operationTags));