docusaurus-plugin-openapi-docs 2.1.2 → 2.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -40,8 +40,6 @@
     "@docusaurus/plugin-content-docs": ">=2.4.1 <=2.4.3",
     "@docusaurus/utils": ">=2.4.1 <=2.4.3",
     "@docusaurus/utils-validation": ">=2.4.1 <=2.4.3",
-    "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
-    "@paloaltonetworks/postman-collection": "^4.1.0",
     "@redocly/openapi-core": "^1.10.5",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
@@ -50,6 +48,8 @@
     "json-schema-merge-allof": "^0.8.1",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
+    "openapi-to-postmanv2": "^4.21.0",
+    "postman-collection": "^4.4.0",
     "slugify": "^1.6.5",
     "swagger2openapi": "^7.0.8",
     "xml-formatter": "^2.6.1"
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "4bb7040ce39ebe38b2a2837ab0c6a8c477a9a546"
+  "gitHead": "060b5777c783abc23cd3744a6d43deb4df80cebd"
 }

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

@@ -44,7 +44,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     ignoreAdditionalProperties: true,
   });
 
-  const required = allOf.reduce((acc, cur) => {
+  const mergedRequired = allOf.reduce((acc, cur) => {
     if (Array.isArray(cur.required)) {
       const next = [...acc, ...cur.required];
       return next;
@@ -52,7 +52,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     return acc;
   }, [] as any);
 
-  return { mergedSchemas, required };
+  return { mergedSchemas, mergedRequired };
 }
 
 /**
@@ -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,
@@ -260,9 +270,8 @@ function createItems(schema: SchemaObject) {
     // TODO: figure out if and how we should pass merged required array
     const {
       mergedSchemas,
-    }: { mergedSchemas: SchemaObject; required: string[] } = mergeAllOf(
-      schema.items?.allOf
-    );
+    }: { mergedSchemas: SchemaObject; mergedRequired: string[] | boolean } =
+      mergeAllOf(schema.items?.allOf);
 
     // Handles combo anyOf/oneOf + properties
     if (
@@ -595,8 +604,19 @@ function createEdges({
   required,
   discriminator,
 }: EdgeProps): any {
-  const schemaName = getSchemaName(schema);
+  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(
       name,
@@ -618,11 +638,22 @@ function createEdges({
   }
 
   if (schema.allOf !== undefined) {
-    const {
-      mergedSchemas,
-      required,
-    }: { mergedSchemas: SchemaObject; required: string[] | boolean } =
-      mergeAllOf(schema.allOf);
+    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 ||
@@ -668,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,
@@ -731,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,
@@ -762,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;
 }