docusaurus-plugin-openapi-docs 2.1.3 → 2.2.0

package/src/index.ts

@@ -40,6 +40,7 @@ export function isURL(str: string): boolean {
 
 export function getDocsPluginConfig(
   presetsPlugins: any[],
+  plugin: string,
   pluginId: string
 ): Object | undefined {
   // eslint-disable-next-line array-callback-return
@@ -51,10 +52,7 @@ export function getDocsPluginConfig(
       }
 
       // Search plugin-content-docs instances
-      if (
-        typeof data[0] === "string" &&
-        data[0] === "@docusaurus/plugin-content-docs"
-      ) {
+      if (typeof data[0] === "string" && data[0] === plugin) {
         const configPluginId = data[1].id ? data[1].id : "default";
         if (configPluginId === pluginId) {
           return data[1];
@@ -70,7 +68,7 @@ export function getDocsPluginConfig(
     }
 
     // Search plugin-content-docs instances
-    if (filteredConfig[0] === "@docusaurus/plugin-content-docs") {
+    if (filteredConfig[0] === plugin) {
       const configPluginId = filteredConfig[1].id
         ? filteredConfig[1].id
         : "default";
@@ -94,14 +92,22 @@ export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
-  const { config, docsPluginId } = options;
+  const {
+    config,
+    docsPlugin = "@docusaurus/plugin-content-docs",
+    docsPluginId,
+  } = options;
   const { siteDir, siteConfig } = context;
 
   // Get routeBasePath and path from plugin-content-docs or preset
   const presets: any = siteConfig.presets;
   const plugins: any = siteConfig.plugins;
   const presetsPlugins = presets.concat(plugins);
-  let docData: any = getDocsPluginConfig(presetsPlugins, docsPluginId);
+  let docData: any = getDocsPluginConfig(
+    presetsPlugins,
+    docsPlugin,
+    docsPluginId
+  );
   let docRouteBasePath = docData ? docData.routeBasePath : undefined;
   let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
@@ -113,6 +119,7 @@ export default function pluginOpenAPIDocs(
       markdownGenerators,
       downloadUrl,
       sidebarOptions,
+      disableCompression,
     } = options;
 
     // Remove trailing slash before proceeding
@@ -120,7 +127,7 @@ export default function pluginOpenAPIDocs(
 
     // Override docPath if pluginId provided
     if (pluginId) {
-      docData = getDocsPluginConfig(presetsPlugins, pluginId);
+      docData = getDocsPluginConfig(presetsPlugins, docsPlugin, pluginId);
       docRouteBasePath = docData ? docData.routeBasePath : undefined;
       docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     }
@@ -299,7 +306,7 @@ custom_edit_url: null
 
       loadedApi.map(async (item) => {
         if (item.type === "info") {
-          if (downloadUrl && isURL(downloadUrl)) {
+          if (downloadUrl) {
             item.downloadUrl = downloadUrl;
           }
         }
@@ -313,9 +320,11 @@ custom_edit_url: null
           // const deserialize = (s: any) => {
           //   return zlib.inflateSync(Buffer.from(s, "base64")).toString();
           // };
-          item.json = zlib
-            .deflateSync(JSON.stringify(item.api))
-            .toString("base64");
+          disableCompression === true
+            ? (item.json = JSON.stringify(item.api))
+            : (item.json = zlib
+                .deflateSync(JSON.stringify(item.api))
+                .toString("base64"));
           let infoBasePath = `${outputDir}/${item.infoId}`;
           if (docRouteBasePath) {
             infoBasePath = `${docRouteBasePath}/${outputDir
@@ -468,7 +477,7 @@ custom_edit_url: null
       cwd: path.resolve(apiDir, "schemas"),
       deep: 1,
     });
-    const sidebarFile = await Globby(["sidebar.js"], {
+    const sidebarFile = await Globby(["sidebar.{js,ts}"], {
       cwd: path.resolve(apiDir),
       deep: 1,
     });
@@ -523,6 +532,7 @@ custom_edit_url: null
         version: version,
         label: metadata.label,
         baseUrl: metadata.baseUrl,
+        downloadUrl: metadata.downloadUrl,
       });
     }
 
@@ -673,6 +683,7 @@ custom_edit_url: null
           delete parentConfig.version;
           delete parentConfig.label;
           delete parentConfig.baseUrl;
+          delete parentConfig.downloadUrl;
 
           // TODO: handle when no versions are defined by version command is passed
           if (versionId === "all") {

package/src/markdown/createRequestSchema.ts

@@ -108,12 +108,6 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
     return undefined;
   }
 
-  // we don't show the table if there is no properties to show
-  if (firstBody.properties !== undefined) {
-    if (Object.keys(firstBody.properties).length === 0) {
-      return undefined;
-    }
-  }
   return create("MimeTabs", {
     className: "openapi-tabs__mime",
     children: [

package/src/markdown/createResponseSchema.ts

@@ -60,12 +60,6 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
           return undefined;
         }
 
-        if (firstBody?.properties !== undefined) {
-          if (Object.keys(firstBody?.properties).length === 0) {
-            return undefined;
-          }
-        }
-
         return create("TabItem", {
           label: `${mimeType}`,
           value: `${mimeType}`,

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/markdown/createSchema.ts

@@ -129,6 +129,16 @@ function createAnyOneOf(schema: SchemaObject): any {
  */
 function createProperties(schema: SchemaObject) {
   const discriminator = schema.discriminator;
+  if (Object.keys(schema.properties!).length === 0) {
+    return create("SchemaItem", {
+      collapsible: false,
+      name: "",
+      required: false,
+      schemaName: "object",
+      qualifierMessage: undefined,
+      schema: {},
+    });
+  }
   return Object.entries(schema.properties!).map(([key, val]) => {
     return createEdges({
       name: key,
@@ -594,6 +604,18 @@ function createEdges({
   required,
   discriminator,
 }: EdgeProps): any {
+  if (SCHEMA_TYPE === "request") {
+    if (schema.readOnly && schema.readOnly === true) {
+      return undefined;
+    }
+  }
+
+  if (SCHEMA_TYPE === "response") {
+    if (schema.writeOnly && schema.writeOnly === true) {
+      return undefined;
+    }
+  }
+
   const schemaName = getSchemaName(schema);
   if (discriminator !== undefined && discriminator.propertyName === name) {
     return createPropertyDiscriminator(
@@ -619,6 +641,19 @@ function createEdges({
     const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
       schema.allOf
     );
+
+    if (SCHEMA_TYPE === "request") {
+      if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
+        return undefined;
+      }
+    }
+
+    if (SCHEMA_TYPE === "response") {
+      if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+        return undefined;
+      }
+    }
+
     const mergedSchemaName = getSchemaName(mergedSchemas);
     if (
       mergedSchemas.oneOf !== undefined ||
@@ -664,18 +699,6 @@ function createEdges({
       );
     }
 
-    if (SCHEMA_TYPE === "request") {
-      if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
-        return undefined;
-      }
-    }
-
-    if (SCHEMA_TYPE === "response") {
-      if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
-        return undefined;
-      }
-    }
-
     return create("SchemaItem", {
       collapsible: false,
       name,
@@ -727,18 +750,6 @@ function createEdges({
     );
   }
 
-  if (SCHEMA_TYPE === "request") {
-    if (schema.readOnly && schema.readOnly === true) {
-      return undefined;
-    }
-  }
-
-  if (SCHEMA_TYPE === "response") {
-    if (schema.writeOnly && schema.writeOnly === true) {
-      return undefined;
-    }
-  }
-
   // primitives and array of non-objects
   return create("SchemaItem", {
     collapsible: false,
@@ -758,6 +769,17 @@ export function createNodes(
   schemaType: "request" | "response"
 ): any {
   SCHEMA_TYPE = schemaType;
+  if (SCHEMA_TYPE === "request") {
+    if (schema.readOnly && schema.readOnly === true) {
+      return undefined;
+    }
+  }
+
+  if (SCHEMA_TYPE === "response") {
+    if (schema.writeOnly && schema.writeOnly === true) {
+      return undefined;
+    }
+  }
   const nodes = [];
   // if (schema.discriminator !== undefined) {
   //   return createDiscriminator(schema);

package/src/markdown/createStatusCodes.ts

@@ -285,7 +285,7 @@ export function createStatusCodes({ label, id, responses }: Props) {
                   responseHeaders &&
                     createDetails({
                       className: "openapi-markdown__details",
-                      "data-collaposed": true,
+                      "data-collapsed": true,
                       open: false,
                       style: { textAlign: "left", marginBottom: "1rem" },
                       children: [

package/src/markdown/utils.ts

@@ -47,3 +47,25 @@ export const lessThan =
 export const greaterThan =
   /(?<!(button|code|details|summary|hr|br|span|strong|small|table|thead|tbody|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|bold|a|li|ol|ul|img|svg|div|center|\/|\s|"|'))>/gu;
 export const codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
+export const curlyBrackets = /([{}])/g;
+export const codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
+
+export function clean(value: string | undefined): string {
+  if (!value) {
+    return "";
+  }
+
+  let sections = value.split(codeBlock);
+  for (let sectionIndex in sections) {
+    if (!sections[sectionIndex].startsWith("`")) {
+      sections[sectionIndex] = sections[sectionIndex]
+        .replace(lessThan, "&lt;")
+        .replace(greaterThan, "&gt;")
+        .replace(codeFence, function (match) {
+          return match.replace(/\\>/g, ">");
+        })
+        .replace(curlyBrackets, "\\$1");
+    }
+  }
+  return sections.join("");
+}

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

@@ -8,15 +8,15 @@
 import path from "path";
 
 import { Globby, GlobExcludeDefault, posixPath } from "@docusaurus/utils";
-import Converter from "@paloaltonetworks/openapi-to-postmanv2";
-import sdk from "@paloaltonetworks/postman-collection";
-import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 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 Converter from "openapi-to-postmanv2";
+import Collection from "postman-collection";
+import sdk from "postman-collection";
 
 import { sampleRequestFromSchema } from "./createRequestExample";
 import { OpenApiObject, TagGroupObject, TagObject } from "./types";
@@ -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/openapi-to-postmanv2.d.ts

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-declare module "@paloaltonetworks/openapi-to-postmanv2" {
+declare module "openapi-to-postmanv2" {
   export default any;
 }

package/src/options.ts

@@ -23,6 +23,7 @@ const markdownGenerators = Joi.object({
 
 export const OptionsSchema = Joi.object({
   id: Joi.string().required(),
+  docsPlugin: Joi.string(),
   docsPluginId: Joi.string().required(),
   config: Joi.object()
     .pattern(
@@ -38,6 +39,7 @@ export const OptionsSchema = Joi.object({
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
         showSchemas: Joi.boolean(),
+        disableCompression: Joi.boolean(),
         version: Joi.string().when("versions", {
           is: Joi.exist(),
           then: Joi.required(),
@@ -57,6 +59,7 @@ export const OptionsSchema = Joi.object({
             outputDir: Joi.string().required(),
             label: Joi.string().required(),
             baseUrl: Joi.string().required(),
+            downloadUrl: Joi.string(),
           })
         ),
       })

package/src/postman-collection.d.ts

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-declare module "@paloaltonetworks/postman-collection" {
+declare module "postman-collection" {
   export default any;
 }

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,25 @@ 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));
+
+  if (sidebarOptions.groupPathsBy !== "tagGroup") {
+    apiTags = uniq(apiTags.concat(operationTags, schemaTags));
+  }
 
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
@@ -107,9 +116,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 +195,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 +233,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),
       },
     ];
   }
@@ -248,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[] = [];
@@ -263,24 +283,32 @@ export default function generateSidebarSlice(
         collapsible: true,
         collapsed: true,
         items: groupByTags(
-          api as ApiPageMetadata[],
+          api,
           sidebarOptions,
           options,
           [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 as ApiPageMetadata[],
-      sidebarOptions,
-      options,
-      tags,
-      docPath
-    );
+    sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
   }
 
   return sidebarSlice;