docusaurus-plugin-openapi-docs 0.0.0-393 → 0.0.0-396

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-393",
+  "version": "0.0.0-396",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,8 +28,8 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
-    "@docusaurus/types": "2.0.0-beta.21",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.22",
+    "@docusaurus/types": "2.0.0-beta.22",
     "@types/fs-extra": "^9.0.13",
     "@types/js-yaml": "^4.0.5",
     "@types/json-pointer": "^1.0.31",
@@ -40,10 +40,10 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^9.0.9",
-    "@docusaurus/mdx-loader": "2.0.0-beta.21",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
-    "@docusaurus/utils": "2.0.0-beta.21",
-    "@docusaurus/utils-validation": "2.0.0-beta.21",
+    "@docusaurus/mdx-loader": "2.0.0-beta.22",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.22",
+    "@docusaurus/utils": "2.0.0-beta.22",
+    "@docusaurus/utils-validation": "2.0.0-beta.22",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
     "@redocly/openapi-core": "^1.0.0-beta.103",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "6b19eaff1627c28fe3c4a9267dd28d0433b7f616"
+  "gitHead": "958b9c6e0b370afe79572dfea950d2be33f41cc0"
 }

package/src/markdown/createAnyOneOf.ts

@@ -5,18 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { createSchemaDetails } from "./createSchemaDetails";
+import { createRows } from "./createSchemaDetails";
 import { create } from "./utils";
 
-// {
-//   'application/json': {
-//     schema: { properties: [Object], required: [Array], type: 'object' }
-//   }
-// }
-// {
-//   'application/json': { schema: { allOf: [Array], example: [Object] } }
-// }
-
 export function createAnyOneOf(anyOneOf: any[], type: string) {
   if (anyOneOf === undefined) {
     return undefined;
@@ -34,49 +25,21 @@ export function createAnyOneOf(anyOneOf: any[], type: string) {
       }),
       create("SchemaTabs", {
         children: anyOneOf.map((schema, index) => {
-          // Prep schema details
-          let schemaDetails: any = {};
-          schemaDetails["application/json"] = {}; // Placeholder content type
-          schemaDetails["application/json"].schema = {};
           const label = schema.title ? schema.title : `MOD${index + 1}`;
 
           if (schema.properties !== undefined) {
-            schemaDetails["application/json"].schema.properties =
-              schema.properties;
-            schemaDetails["application/json"].schema.required = schema.required;
-            schemaDetails["application/json"].schema.type = "object";
             return create("TabItem", {
               label: label,
               value: `${index}-properties`,
-              children: [
-                create("div", {
-                  children: createSchemaDetails({
-                    title: "Schema",
-                    body: {
-                      content: schemaDetails,
-                    },
-                  }),
-                }),
-              ],
+              children: [createRows({ schema: schema })],
             });
           }
 
           if (schema.allOf !== undefined) {
-            schemaDetails["application/json"].schema.allOf = schema.allOf;
-            schemaDetails["application/json"].schema.example = schema.example;
             return create("TabItem", {
               label: label,
               value: `${index}-allOf`,
-              children: [
-                create("div", {
-                  children: createSchemaDetails({
-                    title: "Schema",
-                    body: {
-                      content: schemaDetails,
-                    },
-                  }),
-                }),
-              ],
+              children: [createRows({ schema: schema })],
             });
           }
 

package/src/markdown/createSchemaDetails.ts

@@ -17,7 +17,6 @@ const mergeAllOf = require("json-schema-merge-allof");
 
 function resolveAllOf(allOf: SchemaObject[]) {
   // Use external library to resolve and merge nested allOf schemas
-  let properties: SchemaObject = {};
   const mergedSchemas = mergeAllOf(allOf, {
     resolvers: {
       readOnly: function () {
@@ -29,10 +28,6 @@ function resolveAllOf(allOf: SchemaObject[]) {
     },
   });
 
-  if (mergedSchemas.properties) {
-    properties = mergedSchemas.properties;
-  }
-
   const required = allOf.reduce((acc, cur) => {
     if (Array.isArray(cur.required)) {
       const next = [...acc, ...cur.required];
@@ -41,7 +36,7 @@ function resolveAllOf(allOf: SchemaObject[]) {
     return acc;
   }, [] as string[]);
 
-  return { properties, required };
+  return { mergedSchemas, required };
 }
 
 interface RowProps {
@@ -51,7 +46,58 @@ interface RowProps {
 }
 
 function createRow({ name, schema, required }: RowProps) {
-  const schemaName = getSchemaName(schema, true);
+  const schemaName = getSchemaName(schema);
+
+  // array
+  if (schema.type === "array" && schema.items) {
+    return create("SchemaItem", {
+      collapsible: true,
+      className: "schemaItem",
+      children: [
+        createDetails({
+          children: [
+            createDetailsSummary({
+              children: [
+                create("strong", { children: name }),
+                create("span", {
+                  style: { opacity: "0.6" },
+                  children: ` ${schemaName}`,
+                }),
+                guard(required, () => [
+                  create("strong", {
+                    style: {
+                      fontSize: "var(--ifm-code-font-size)",
+                      color: "var(--openapi-required)",
+                    },
+                    children: " required",
+                  }),
+                ]),
+              ],
+            }),
+            create("div", {
+              style: { marginLeft: "1rem" },
+              children: [
+                guard(getQualifierMessage(schema), (message) =>
+                  create("div", {
+                    style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                    children: createDescription(message),
+                  })
+                ),
+                guard(schema.description, (description) =>
+                  create("div", {
+                    style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                    children: createDescription(description),
+                  })
+                ),
+                createRows({ schema: schema.items }),
+              ],
+            }),
+          ],
+        }),
+      ],
+    });
+  }
+
   if (schemaName && (schemaName === "object" || schemaName === "object[]")) {
     return create("SchemaItem", {
       collapsible: true,
@@ -101,12 +147,13 @@ function createRow({ name, schema, required }: RowProps) {
     });
   }
 
+  // primitive
   return create("SchemaItem", {
     collapsible: false,
     name,
     required,
     schemaDescription: schema.description,
-    schemaName: getSchemaName(schema, true),
+    schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),
   });
 }
@@ -115,7 +162,17 @@ interface RowsProps {
   schema: SchemaObject;
 }
 
-function createRows({ schema }: RowsProps): string | undefined {
+export function createRows({ schema }: RowsProps): string | undefined {
+  // oneOf
+  if (schema.oneOf !== undefined) {
+    return createAnyOneOf(schema.oneOf, "oneOf");
+  }
+
+  // anyOf
+  if (schema.anyOf !== undefined) {
+    return createAnyOneOf(schema.anyOf, "anyOf");
+  }
+
   // object
   if (schema.properties !== undefined) {
     return create("ul", {
@@ -131,39 +188,49 @@ function createRows({ schema }: RowsProps): string | undefined {
     });
   }
 
-  // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
+  // allOf
   if (schema.allOf !== undefined) {
-    const { properties, required } = resolveAllOf(schema.allOf);
-    return create("div", {
-      children: [
-        create("span", {
-          className: "badge badge--info",
-          style: { marginBottom: "1rem" },
-          children: "allOf",
-        }),
-        Object.entries(properties).map(([key, val]) =>
-          createRow({
-            name: key,
-            schema: val,
-            required: Array.isArray(required) ? required.includes(key) : false,
-          })
-        ),
-      ],
-    });
-  }
+    const {
+      mergedSchemas,
+      required,
+    }: { mergedSchemas: SchemaObject; required: string[] } = resolveAllOf(
+      schema.allOf
+    );
+    // Adds support one more level deep
+    if (mergedSchemas.oneOf !== undefined) {
+      return createAnyOneOf(mergedSchemas.oneOf, "oneOf");
+    }
 
-  // Adds support one more level deep
-  if (schema.oneOf !== undefined) {
-    return createAnyOneOf(schema.oneOf, "oneOf");
-  }
+    if (mergedSchemas.anyOf !== undefined) {
+      return createAnyOneOf(mergedSchemas.anyOf, "anyOf");
+    }
 
-  if (schema.anyOf !== undefined) {
-    return createAnyOneOf(schema.anyOf, "anyOf");
-  }
+    // array
+    if (mergedSchemas.items !== undefined) {
+      return createRows({ schema: schema.items as SchemaObject });
+    }
 
-  // array
-  if (schema.items !== undefined) {
-    return createRows({ schema: schema.items });
+    if (mergedSchemas.properties !== undefined) {
+      return create("div", {
+        children: [
+          create("span", {
+            className: "badge badge--info",
+            style: { marginBottom: "1rem" },
+            children: "allOf",
+          }),
+          Object.entries(mergedSchemas.properties as SchemaObject).map(
+            ([key, val]) =>
+              createRow({
+                name: key,
+                schema: val as SchemaObject,
+                required: Array.isArray(required)
+                  ? required.includes(key)
+                  : false,
+              })
+          ),
+        ],
+      });
+    }
   }
 
   // primitive
@@ -188,9 +255,14 @@ function createRowsRoot({ schema }: RowsRootProps): any {
     );
   }
 
-  // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
+  // allOf
   if (schema.allOf !== undefined) {
-    const { properties, required } = resolveAllOf(schema.allOf);
+    const {
+      mergedSchemas,
+      required,
+    }: { mergedSchemas: SchemaObject; required: string[] } = resolveAllOf(
+      schema.allOf
+    );
     return create("div", {
       children: [
         create("span", {
@@ -198,22 +270,26 @@ function createRowsRoot({ schema }: RowsRootProps): any {
           style: { marginBottom: "1rem" },
           children: "allOf",
         }),
-        Object.entries(properties).map(([key, val]) =>
-          createRow({
-            name: key,
-            schema: val,
-            required: Array.isArray(required) ? required.includes(key) : false,
-          })
+        Object.entries(mergedSchemas.properties as SchemaObject).map(
+          ([key, val]) =>
+            createRow({
+              name: key,
+              schema: val as SchemaObject,
+              required: Array.isArray(required)
+                ? required.includes(key)
+                : false,
+            })
         ),
       ],
     });
   }
 
-  // TODO: This is top-level only - add support for nested oneOf/anyOf
+  // oneOf
   if (schema.oneOf !== undefined) {
     return createAnyOneOf(schema.oneOf, "oneOf");
   }
 
+  // anyOf
   if (schema.anyOf !== undefined) {
     return createAnyOneOf(schema.anyOf, "anyOf");
   }

package/src/markdown/schema.ts

@@ -8,22 +8,36 @@
 import { SchemaObject } from "../openapi/types";
 
 function prettyName(schema: SchemaObject, circular?: boolean) {
-  if (schema.$ref) {
-    return schema.$ref.replace("#/components/schemas/", "") + circular
-      ? " (circular)"
-      : "";
-  }
-
   if (schema.format) {
     return schema.format;
   }
 
   if (schema.allOf) {
+    if (typeof schema.allOf[0] === "string") {
+      // @ts-ignore
+      if (schema.allOf[0].includes("circular")) {
+        return schema.allOf[0];
+      }
+    }
+    return "object";
+  }
+
+  if (schema.oneOf) {
+    return "object";
+  }
+
+  if (schema.anyOf) {
     return "object";
   }
 
   if (schema.type === "object") {
     return schema.xml?.name ?? schema.type;
+    // return schema.type;
+  }
+
+  if (schema.type === "array") {
+    return schema.xml?.name ?? schema.type;
+    // return schema.type;
   }
 
   return schema.title ?? schema.type;
@@ -42,8 +56,6 @@ export function getSchemaName(
 
 export function getQualifierMessage(schema?: SchemaObject): string | undefined {
   // TODO:
-  // - maxItems
-  // - minItems
   // - uniqueItems
   // - maxProperties
   // - minProperties
@@ -52,9 +64,10 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     return undefined;
   }
 
-  if (schema.items) {
-    return getQualifierMessage(schema.items);
-  }
+  // TODO: This doesn't seem right
+  // if (schema.items) {
+  //   return getQualifierMessage(schema.items);
+  // }
 
   let message = "**Possible values:** ";
 
@@ -107,6 +120,14 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
+  if (schema.minItems) {
+    qualifierGroups.push(`items >= ${schema.minItems}`);
+  }
+
+  if (schema.maxItems) {
+    qualifierGroups.push(`items <= ${schema.maxItems}`);
+  }
+
   if (qualifierGroups.length === 0) {
     return undefined;
   }

package/src/openapi/openapi.ts

@@ -13,7 +13,6 @@ import sdk from "@paloaltonetworks/postman-collection";
 import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 import fs from "fs-extra";
-import JsonRefs from "json-refs";
 import { kebabCase } from "lodash";
 
 import { isURL } from "../index";
@@ -26,16 +25,8 @@ import {
   TagPageMetadata,
 } from "../types";
 import { sampleFromSchema } from "./createExample";
-import { OpenApiObject, OpenApiObjectWithRef, TagObject } from "./types";
-import { loadAndBundleSpec } from "./utils/loadAndBundleSpec";
-
-/**
- * Finds any reference objects in the OpenAPI definition and resolves them to a finalized value.
- */
-async function resolveRefs(openapiData: OpenApiObjectWithRef) {
-  const { resolved } = await JsonRefs.resolveRefs(openapiData);
-  return resolved as OpenApiObject;
-}
+import { OpenApiObject, TagObject } from "./types";
+import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
  * Convenience function for converting raw JSON to a Postman Collection object.
@@ -62,7 +53,7 @@ function jsonToCollection(data: OpenApiObject): Promise<Collection> {
 async function createPostmanCollection(
   openapiData: OpenApiObject
 ): Promise<Collection> {
-  const data = JSON.parse(JSON.stringify(openapiData)) as OpenApiObject;
+  const data = openapiData as OpenApiObject;
 
   // Including `servers` breaks postman, so delete all of them.
   delete data.servers;
@@ -243,17 +234,13 @@ function bindCollectionToApiItems(
 interface OpenApiFiles {
   source: string;
   sourceDirName: string;
-  data: OpenApiObjectWithRef;
+  data: OpenApiObject;
 }
 
 export async function readOpenapiFiles(
   openapiPath: string,
   options: APIOptions
 ): Promise<OpenApiFiles[]> {
-  // TODO: determine if this should be an API option
-  // Forces the json-schema-ref-parser
-  const parseJsonRefs = true;
-
   if (!isURL(openapiPath)) {
     const stat = await fs.lstat(openapiPath);
     if (stat.isDirectory()) {
@@ -274,10 +261,9 @@ export async function readOpenapiFiles(
         sources.map(async (source) => {
           // TODO: make a function for this
           const fullPath = path.join(openapiPath, source);
-          const data = (await loadAndBundleSpec(
-            fullPath,
-            parseJsonRefs
-          )) as OpenApiObjectWithRef;
+          const data = (await loadAndResolveSpec(
+            fullPath
+          )) as unknown as OpenApiObject;
           return {
             source: fullPath, // This will be aliased in process.
             sourceDirName: path.dirname(source),
@@ -287,10 +273,9 @@ export async function readOpenapiFiles(
       );
     }
   }
-  const data = (await loadAndBundleSpec(
-    openapiPath,
-    parseJsonRefs
-  )) as OpenApiObjectWithRef;
+  const data = (await loadAndResolveSpec(
+    openapiPath
+  )) as unknown as OpenApiObject;
   return [
     {
       source: openapiPath, // This will be aliased in process.
@@ -305,30 +290,46 @@ export async function processOpenapiFiles(
   sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[]]> {
   const promises = files.map(async (file) => {
-    const processedFile = await processOpenapiFile(file.data, sidebarOptions);
-    const itemsObjectsArray = processedFile[0].map((item) => ({
-      ...item,
-    }));
-    const tags = processedFile[1];
-    return [itemsObjectsArray, tags];
+    if (file.data !== undefined) {
+      const processedFile = await processOpenapiFile(file.data, sidebarOptions);
+      const itemsObjectsArray = processedFile[0].map((item) => ({
+        ...item,
+      }));
+      const tags = processedFile[1];
+      return [itemsObjectsArray, tags];
+    }
+    console.warn(
+      chalk.yellow(
+        `WARNING: the following OpenAPI spec returned undefined: ${file.source}`
+      )
+    );
+    return [];
   });
   const metadata = await Promise.all(promises);
   const items = metadata
     .map(function (x) {
       return x[0];
     })
-    .flat();
-  const tags = metadata.map(function (x) {
-    return x[1];
-  });
+    .flat()
+    .filter(function (x) {
+      // Remove undefined items due to transient parsing errors
+      return x !== undefined;
+    });
+  const tags = metadata
+    .map(function (x) {
+      return x[1];
+    })
+    .filter(function (x) {
+      // Remove undefined tags due to transient parsing errors
+      return x !== undefined;
+    });
   return [items as ApiMetadata[], tags as TagObject[]];
 }
 
 export async function processOpenapiFile(
-  openapiDataWithRefs: OpenApiObjectWithRef,
+  openapiData: OpenApiObject,
   sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[]]> {
-  const openapiData = await resolveRefs(openapiDataWithRefs);
   const postmanCollection = await createPostmanCollection(openapiData);
   const items = createItems(openapiData, sidebarOptions);
 

package/src/openapi/types.ts

@@ -20,6 +20,7 @@ export interface OpenApiObject {
   security?: SecurityRequirementObject[];
   tags?: TagObject[];
   externalDocs?: ExternalDocumentationObject;
+  swagger?: string;
 }
 
 export interface OpenApiObjectWithRef {