docusaurus-plugin-openapi-docs 2.1.3 → 2.2.1

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;

package/src/types.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import type Request from "@paloaltonetworks/postman-collection";
+import type Request from "postman-collection";
 
 import {
   InfoObject,
@@ -23,6 +23,7 @@ export type {
 } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
   id?: string;
+  docsPlugin?: string;
   docsPluginId: string;
   config: {
     [key: string]: APIOptions;
@@ -46,6 +47,7 @@ export interface APIOptions {
   proxy?: string;
   markdownGenerators?: MarkdownGenerator;
   showSchemas?: boolean;
+  disableCompression?: boolean;
 }
 
 export interface MarkdownGenerator {
@@ -68,6 +70,7 @@ export interface APIVersionOptions {
   outputDir: string;
   label: string;
   baseUrl: string;
+  downloadUrl?: string;
 }
 
 export interface LoadedContent {