docusaurus-plugin-openapi-docs 3.0.0-beta.8 → 3.0.0

package/src/markdown/createSchema.ts

@@ -6,6 +6,7 @@
  * ========================================================================== */
 
 import clsx from "clsx";
+import isEmpty from "lodash/isEmpty";
 
 import {
   createClosingArrayBracket,
@@ -44,7 +45,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 +53,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     return acc;
   }, [] as any);
 
-  return { mergedSchemas, required };
+  return { mergedSchemas, mergedRequired };
 }
 
 /**
@@ -129,6 +130,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,
@@ -146,27 +157,29 @@ function createProperties(schema: SchemaObject) {
  */
 function createAdditionalProperties(schema: SchemaObject) {
   const additionalProperties = schema.additionalProperties;
-  const type: string | unknown = additionalProperties?.type;
+  if (!additionalProperties) return [];
+
   // Handle free-form objects
-  if (String(additionalProperties) === "true" && schema.type === "object") {
+  if (additionalProperties === true || isEmpty(additionalProperties)) {
     return create("SchemaItem", {
       name: "property name*",
       required: false,
       schemaName: "any",
-      qualifierMessage: getQualifierMessage(schema.additionalProperties),
+      qualifierMessage: getQualifierMessage(schema),
       schema: schema,
       collapsible: false,
       discriminator: false,
     });
   }
+
+  // objects, arrays, complex schemas
   if (
-    (type === "object" || type === "array") &&
-    (additionalProperties?.properties ||
-      additionalProperties?.items ||
-      additionalProperties?.allOf ||
-      additionalProperties?.additionalProperties ||
-      additionalProperties?.oneOf ||
-      additionalProperties?.anyOf)
+    additionalProperties.properties ||
+    additionalProperties.items ||
+    additionalProperties.allOf ||
+    additionalProperties.additionalProperties ||
+    additionalProperties.oneOf ||
+    additionalProperties.anyOf
   ) {
     const title = additionalProperties.title as string;
     const schemaName = getSchemaName(additionalProperties);
@@ -180,52 +193,27 @@ function createAdditionalProperties(schema: SchemaObject) {
     );
   }
 
+  // primitive types
   if (
-    (schema.additionalProperties?.type as string) === "string" ||
-    (schema.additionalProperties?.type as string) === "object" ||
-    (schema.additionalProperties?.type as string) === "boolean" ||
-    (schema.additionalProperties?.type as string) === "integer" ||
-    (schema.additionalProperties?.type as string) === "number"
+    additionalProperties.type === "string" ||
+    additionalProperties.type === "boolean" ||
+    additionalProperties.type === "integer" ||
+    additionalProperties.type === "number"
   ) {
-    const additionalProperties =
-      schema.additionalProperties?.additionalProperties;
-    if (additionalProperties !== undefined) {
-      const type = schema.additionalProperties?.additionalProperties?.type;
-      const schemaName = getSchemaName(
-        schema.additionalProperties?.additionalProperties!
-      );
-      return create("SchemaItem", {
-        name: "property name*",
-        required: false,
-        schemaName: schemaName ?? type,
-        qualifierMessage:
-          schema.additionalProperties ??
-          getQualifierMessage(schema.additionalProperties),
-        schema: schema,
-        collapsible: false,
-        discriminator: false,
-      });
-    }
-    const schemaName = getSchemaName(schema.additionalProperties!);
+    const schemaName = getSchemaName(additionalProperties);
     return create("SchemaItem", {
       name: "property name*",
       required: false,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
-      schema: schema.additionalProperties,
+      schema: additionalProperties,
       collapsible: false,
       discriminator: false,
     });
   }
-  return Object.entries(schema.additionalProperties!).map(([key, val]) =>
-    createEdges({
-      name: key,
-      schema: val,
-      required: Array.isArray(schema.required)
-        ? schema.required.includes(key)
-        : false,
-    })
-  );
+
+  // unknown
+  return [];
 }
 
 /**
@@ -260,9 +248,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 +582,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 +616,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 +677,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 +728,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 +747,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);
@@ -774,7 +770,13 @@ export function createNodes(
   if (schema.allOf !== undefined) {
     const { mergedSchemas } = mergeAllOf(schema.allOf);
 
-    // allOf seems to always result in properties
+    if (
+      mergedSchemas.oneOf !== undefined ||
+      mergedSchemas.anyOf !== undefined
+    ) {
+      nodes.push(createAnyOneOf(mergedSchemas));
+    }
+
     if (mergedSchemas.properties !== undefined) {
       nodes.push(createProperties(mergedSchemas));
     }

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/createVersionBadge.ts

@@ -9,10 +9,14 @@ import { create, guard } from "./utils";
 
 export function createVersionBadge(version: string | undefined) {
   return guard(version, (version) => [
-    create("span", {
-      className: "theme-doc-version-badge badge badge--secondary",
-      children: `Version: ${escape(version)}`,
-    }),
+    create(
+      "span",
+      {
+        className: "theme-doc-version-badge badge badge--secondary",
+        children: `Version: ${escape(version)}`,
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ]);
 }

package/src/markdown/utils.ts

@@ -61,7 +61,7 @@ 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 curlyBrackets = /([{}])/g;
 export const codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
 
 export function clean(value: string | undefined): string {

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

@@ -341,7 +341,7 @@ export type SchemaObject = Omit<
   not?: SchemaObject;
   items?: SchemaObject;
   properties?: Map<SchemaObject>;
-  additionalProperties?: Map<SchemaObject>;
+  additionalProperties?: boolean | SchemaObject;
 
   // OpenAPI additions
   nullable?: boolean;
@@ -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;