docusaurus-plugin-openapi-docs 0.0.0-722 → 0.0.0-723

package/lib/markdown/createSchema.test.js

@@ -34,6 +34,7 @@ const createSchema_1 = require("./createSchema");
 describe("createNodes", () => {
     it("should create readable MODs for oneOf primitive properties", () => {
         const schema = {
+            "x-tags": ["clown"],
             type: "object",
             properties: {
                 oneOfProperty: {

package/lib/openapi/openapi.js

@@ -61,7 +61,7 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData, options, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6;
     // TODO: Find a better way to handle this
     let items = [];
     const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
@@ -324,42 +324,47 @@ function createItems(openapiData, options, sidebarOptions) {
             items.push(apiPage);
         }
     }
-    if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true) {
+    if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
+        Object.entries((_1 = (_0 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _0 === void 0 ? void 0 : _0.schemas) !== null && _1 !== void 0 ? _1 : {})
+            .flatMap(([_, s]) => s["x-tags"])
+            .filter((item) => !!item).length > 0) {
         // Gather schemas
-        for (let [schema, schemaObject] of Object.entries((_1 = (_0 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _0 === void 0 ? void 0 : _0.schemas) !== null && _1 !== void 0 ? _1 : {})) {
-            const baseIdSpaces = (_3 = (_2 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _2 === void 0 ? void 0 : _2.replace(" ", "-").toLowerCase()) !== null && _3 !== void 0 ? _3 : "";
-            const baseId = (0, kebabCase_1.default)(baseIdSpaces);
-            const schemaDescription = schemaObject.description;
-            let splitDescription;
-            if (schemaDescription) {
-                splitDescription = schemaDescription.match(/[^\r\n]+/g);
-            }
-            const schemaPage = {
-                type: "schema",
-                id: baseId,
-                infoId: infoId !== null && infoId !== void 0 ? infoId : "",
-                unversionedId: baseId,
-                title: schemaObject.title
-                    ? schemaObject.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                    : schema,
-                description: schemaObject.description
-                    ? schemaObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                    : "",
-                frontMatter: {
-                    description: splitDescription
-                        ? splitDescription[0]
-                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                            .replace(/\s+$/, "")
+        for (let [schema, schemaObject] of Object.entries((_3 = (_2 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _2 === void 0 ? void 0 : _2.schemas) !== null && _3 !== void 0 ? _3 : {})) {
+            if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true || schemaObject["x-tags"]) {
+                const baseIdSpaces = (_5 = (_4 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _4 === void 0 ? void 0 : _4.replace(" ", "-").toLowerCase()) !== null && _5 !== void 0 ? _5 : "";
+                const baseId = (0, kebabCase_1.default)(baseIdSpaces);
+                const schemaDescription = schemaObject.description;
+                let splitDescription;
+                if (schemaDescription) {
+                    splitDescription = schemaDescription.match(/[^\r\n]+/g);
+                }
+                const schemaPage = {
+                    type: "schema",
+                    id: baseId,
+                    infoId: infoId !== null && infoId !== void 0 ? infoId : "",
+                    unversionedId: baseId,
+                    title: schemaObject.title
+                        ? schemaObject.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                        : schema,
+                    description: schemaObject.description
+                        ? schemaObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                         : "",
-                },
-                schema: schemaObject,
-            };
-            items.push(schemaPage);
+                    frontMatter: {
+                        description: splitDescription
+                            ? splitDescription[0]
+                                .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                                .replace(/\s+$/, "")
+                            : "",
+                    },
+                    schema: schemaObject,
+                };
+                items.push(schemaPage);
+            }
         }
     }
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Get global tags
-        const tags = (_4 = openapiData.tags) !== null && _4 !== void 0 ? _4 : [];
+        const tags = (_6 = openapiData.tags) !== null && _6 !== void 0 ? _6 : [];
         // Get operation tags
         const apiItems = items.filter((item) => {
             return item.type === "api";

package/lib/openapi/openapi.test.js

@@ -17,6 +17,7 @@ const _1 = require(".");
 describe("openapi", () => {
     describe("readOpenapiFiles", () => {
         it("readOpenapiFiles", async () => {
+            var _a, _b;
             const results = await (0, _1.readOpenapiFiles)((0, utils_1.posixPath)(path_1.default.join(__dirname, "__fixtures__/examples")));
             const categoryMeta = results.find((x) => x.source.endsWith("_category_.json"));
             expect(categoryMeta).toBeFalsy();
@@ -26,6 +27,7 @@ describe("openapi", () => {
             expect(yaml === null || yaml === void 0 ? void 0 : yaml.sourceDirName).toBe(".");
             expect(yaml === null || yaml === void 0 ? void 0 : yaml.data.tags).toBeDefined();
             expect(yaml === null || yaml === void 0 ? void 0 : yaml.data["x-tagGroups"]).toBeDefined();
+            expect((_b = (_a = yaml === null || yaml === void 0 ? void 0 : yaml.data.components) === null || _a === void 0 ? void 0 : _a.schemas) === null || _b === void 0 ? void 0 : _b.HelloString["x-tags"]).toBeDefined();
         });
     });
 });

package/lib/openapi/types.d.ts

@@ -278,6 +278,7 @@ export type SchemaObject = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf"
     externalDocs?: ExternalDocumentationObject;
     example?: any;
     deprecated?: boolean;
+    "x-tags"?: string[];
 };
 export type SchemaObjectWithRef = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf" | "not" | "items" | "properties" | "additionalProperties"> & {
     type?: "string" | "number" | "integer" | "boolean" | "object" | "array";

package/lib/sidebars/index.js

@@ -24,7 +24,7 @@ function isSchemaItem(item) {
     return item.type === "schema";
 }
 function groupByTags(items, sidebarOptions, options, tags, docPath) {
-    let { outputDir, label } = options;
+    let { outputDir, label, showSchemas } = options;
     // Remove trailing slash before proceeding
     outputDir = outputDir.replace(/\/$/, "");
     const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
@@ -43,16 +43,19 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const operationTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
-    // Combine globally defined tags with operation tags
-    // Only include global tag if referenced in operation tags
+    const schemaTags = (0, uniq_1.default)(schemaItems
+        .flatMap((item) => item.schema["x-tags"])
+        .filter((item) => !!item));
+    // Combine globally defined tags with operation and schema tags
+    // Only include global tag if referenced in operation/schema tags
     let apiTags = [];
     tags.flat().forEach((tag) => {
         // Should we also check x-displayName?
-        if (operationTags.includes(tag.name)) {
+        if (operationTags.includes(tag.name) || schemaTags.includes(tag.name)) {
             apiTags.push(tag.name);
         }
     });
-    apiTags = (0, uniq_1.default)(apiTags.concat(operationTags));
+    apiTags = (0, uniq_1.default)(apiTags.concat(operationTags, schemaTags));
     const basePath = docPath
         ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
         : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
@@ -68,7 +71,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             }, item.api.method)
             : (0, clsx_1.default)({
                 "menu__list-item--deprecated": item.schema.deprecated,
-            });
+            }, "schema");
         return {
             type: "doc",
             id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
@@ -126,15 +129,15 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                     : (0, utils_1.posixPath)(path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(tag))),
             };
         }
+        const taggedApiItems = apiItems.filter((item) => { var _a; return !!((_a = item.api.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
+        const taggedSchemaItems = schemaItems.filter((item) => { var _a; return !!((_a = item.schema["x-tags"]) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
         return {
             type: "category",
             label: (_a = tagObject === null || tagObject === void 0 ? void 0 : tagObject["x-displayName"]) !== null && _a !== void 0 ? _a : tag,
             link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
-            items: apiItems
-                .filter((item) => { var _a; return !!((_a = item.api.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); })
-                .map(createDocItem),
+            items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -157,14 +160,16 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
         ];
     }
     let schemas = [];
-    if (schemaItems.length > 0) {
+    if (showSchemas && schemaItems.length > 0) {
         schemas = [
             {
                 type: "category",
                 label: "Schemas",
                 collapsible: sidebarCollapsible,
                 collapsed: sidebarCollapsed,
-                items: schemaItems.map(createDocItem),
+                items: schemaItems
+                    .filter(({ schema }) => !schema["x-tags"])
+                    .map(createDocItem),
             },
         ];
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-722",
+  "version": "0.0.0-723",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "d580c447cf347d6917d449590e25c25bb5936c6e"
+  "gitHead": "3263dd6299867edd790defa2dda09b79c59cb9cb"
 }

package/src/markdown/createSchema.test.ts

@@ -13,6 +13,7 @@ import { SchemaObject } from "../openapi/types";
 describe("createNodes", () => {
   it("should create readable MODs for oneOf primitive properties", () => {
     const schema: SchemaObject = {
+      "x-tags": ["clown"],
       type: "object",
       properties: {
         oneOfProperty: {

package/src/openapi/__fixtures__/examples/openapi.yaml

@@ -40,3 +40,10 @@ x-tagGroups:
     tags:
       - tag3
       - tag4
+
+components:
+  schemas:
+    HelloString:
+      x-tags:
+        - tag1
+      type: string

package/src/openapi/openapi.test.ts

@@ -31,6 +31,10 @@ describe("openapi", () => {
 
       expect(yaml?.data.tags).toBeDefined();
       expect(yaml?.data["x-tagGroups"]).toBeDefined();
+
+      expect(
+        yaml?.data.components?.schemas?.HelloString["x-tags"]
+      ).toBeDefined();
     });
   });
 });

package/src/openapi/openapi.ts

@@ -410,43 +410,53 @@ function createItems(
     }
   }
 
-  if (options?.showSchemas === true) {
+  if (
+    options?.showSchemas === true ||
+    Object.entries(openapiData?.components?.schemas ?? {})
+      .flatMap(([_, s]) => s["x-tags"])
+      .filter((item) => !!item).length > 0
+  ) {
     // Gather schemas
     for (let [schema, schemaObject] of Object.entries(
       openapiData?.components?.schemas ?? {}
     )) {
-      const baseIdSpaces =
-        schemaObject?.title?.replace(" ", "-").toLowerCase() ?? "";
-      const baseId = kebabCase(baseIdSpaces);
-
-      const schemaDescription = schemaObject.description;
-      let splitDescription: any;
-      if (schemaDescription) {
-        splitDescription = schemaDescription.match(/[^\r\n]+/g);
-      }
+      if (options?.showSchemas === true || schemaObject["x-tags"]) {
+        const baseIdSpaces =
+          schemaObject?.title?.replace(" ", "-").toLowerCase() ?? "";
+        const baseId = kebabCase(baseIdSpaces);
+
+        const schemaDescription = schemaObject.description;
+        let splitDescription: any;
+        if (schemaDescription) {
+          splitDescription = schemaDescription.match(/[^\r\n]+/g);
+        }
 
-      const schemaPage: PartialPage<SchemaPageMetadata> = {
-        type: "schema",
-        id: baseId,
-        infoId: infoId ?? "",
-        unversionedId: baseId,
-        title: schemaObject.title
-          ? schemaObject.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-          : schema,
-        description: schemaObject.description
-          ? schemaObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-          : "",
-        frontMatter: {
-          description: splitDescription
-            ? splitDescription[0]
-                .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
-                .replace(/\s+$/, "")
+        const schemaPage: PartialPage<SchemaPageMetadata> = {
+          type: "schema",
+          id: baseId,
+          infoId: infoId ?? "",
+          unversionedId: baseId,
+          title: schemaObject.title
+            ? schemaObject.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+            : schema,
+          description: schemaObject.description
+            ? schemaObject.description.replace(
+                /((?:^|[^\\])(?:\\{2})*)"/g,
+                "$1'"
+              )
             : "",
-        },
-        schema: schemaObject,
-      };
+          frontMatter: {
+            description: splitDescription
+              ? splitDescription[0]
+                  .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                  .replace(/\s+$/, "")
+              : "",
+          },
+          schema: schemaObject,
+        };
 
-      items.push(schemaPage);
+        items.push(schemaPage);
+      }
     }
   }
 

package/src/openapi/types.ts

@@ -352,6 +352,7 @@ export type SchemaObject = Omit<
   externalDocs?: ExternalDocumentationObject;
   example?: any;
   deprecated?: boolean;
+  "x-tags"?: string[];
 };
 
 export type SchemaObjectWithRef = Omit<

package/src/sidebars/index.ts

@@ -25,6 +25,7 @@ import type {
   APIOptions,
   ApiPageMetadata,
   ApiMetadata,
+  InfoPageMetadata,
   SchemaPageMetadata,
 } from "../types";
 
@@ -41,13 +42,13 @@ function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
 }
 
 function groupByTags(
-  items: ApiPageMetadata[],
+  items: ApiMetadata[],
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   tags: TagObject[][],
   docPath: string
 ): ProcessedSidebar {
-  let { outputDir, label } = options;
+  let { outputDir, label, showSchemas } = options;
 
   // Remove trailing slash before proceeding
   outputDir = outputDir.replace(/\/$/, "");
@@ -59,9 +60,9 @@ function groupByTags(
     categoryLinkSource,
   } = sidebarOptions;
 
-  const apiItems = items.filter(isApiItem);
-  const infoItems = items.filter(isInfoItem);
-  const schemaItems = items.filter(isSchemaItem);
+  const apiItems = items.filter(isApiItem) as ApiPageMetadata[];
+  const infoItems = items.filter(isInfoItem) as InfoPageMetadata[];
+  const schemaItems = items.filter(isSchemaItem) as SchemaPageMetadata[];
   const intros = infoItems.map((item: any) => {
     return {
       id: item.id,
@@ -77,17 +78,22 @@ function groupByTags(
       .flatMap((item) => item.api.tags)
       .filter((item): item is string => !!item)
   );
+  const schemaTags = uniq(
+    schemaItems
+      .flatMap((item) => item.schema["x-tags"])
+      .filter((item): item is string => !!item)
+  );
 
-  // Combine globally defined tags with operation tags
-  // Only include global tag if referenced in operation tags
+  // Combine globally defined tags with operation and schema tags
+  // Only include global tag if referenced in operation/schema tags
   let apiTags: string[] = [];
   tags.flat().forEach((tag) => {
     // Should we also check x-displayName?
-    if (operationTags.includes(tag.name!)) {
+    if (operationTags.includes(tag.name!) || schemaTags.includes(tag.name!)) {
       apiTags.push(tag.name!);
     }
   });
-  apiTags = uniq(apiTags.concat(operationTags));
+  apiTags = uniq(apiTags.concat(operationTags, schemaTags));
 
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
@@ -107,9 +113,12 @@ function groupByTags(
             },
             item.api.method
           )
-        : clsx({
-            "menu__list-item--deprecated": item.schema.deprecated,
-          });
+        : clsx(
+            {
+              "menu__list-item--deprecated": item.schema.deprecated,
+            },
+            "schema"
+          );
     return {
       type: "doc" as const,
       id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
@@ -183,15 +192,20 @@ function groupByTags(
         } as SidebarItemCategoryLinkConfig;
       }
 
+      const taggedApiItems = apiItems.filter(
+        (item) => !!item.api.tags?.includes(tag)
+      );
+      const taggedSchemaItems = schemaItems.filter(
+        (item) => !!item.schema["x-tags"]?.includes(tag)
+      );
+
       return {
         type: "category" as const,
         label: tagObject?.["x-displayName"] ?? tag,
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
-        items: apiItems
-          .filter((item) => !!item.api.tags?.includes(tag))
-          .map(createDocItem),
+        items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
       };
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -216,14 +230,16 @@ function groupByTags(
   }
 
   let schemas: SidebarItemCategory[] = [];
-  if (schemaItems.length > 0) {
+  if (showSchemas && schemaItems.length > 0) {
     schemas = [
       {
         type: "category" as const,
         label: "Schemas",
         collapsible: sidebarCollapsible!,
         collapsed: sidebarCollapsed!,
-        items: schemaItems.map(createDocItem),
+        items: schemaItems
+          .filter(({ schema }) => !schema["x-tags"])
+          .map(createDocItem),
       },
     ];
   }
@@ -263,7 +279,7 @@ export default function generateSidebarSlice(
         collapsible: true,
         collapsed: true,
         items: groupByTags(
-          api as ApiPageMetadata[],
+          api,
           sidebarOptions,
           options,
           [filteredTags],
@@ -274,13 +290,7 @@ export default function generateSidebarSlice(
       sidebarSlice.push(groupCategory);
     });
   } else if (sidebarOptions.groupPathsBy === "tag") {
-    sidebarSlice = groupByTags(
-      api as ApiPageMetadata[],
-      sidebarOptions,
-      options,
-      tags,
-      docPath
-    );
+    sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
   }
 
   return sidebarSlice;