docusaurus-plugin-openapi-docs 1.0.6 → 1.1.0

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
@@ -107,6 +119,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/markdown/utils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-export type Children = string | undefined | (string | undefined)[];
+export type Children = string | undefined | (string | string[] | undefined)[];
 
 export type Props = Record<string, any> & { children?: Children };
 
@@ -33,7 +33,10 @@ export function guard<T>(
 
 export function render(children: Children): string {
   if (Array.isArray(children)) {
-    return children.filter((c) => c !== undefined).join("");
+    const filteredChildren = children.filter((c) => c !== undefined);
+    return filteredChildren
+      .map((i: any) => (Array.isArray(i) ? i.join("") : i))
+      .join("");
   }
   return children ?? "";
 }

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

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -0,0 +1,123 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import $RefParser from "@apidevtools/json-schema-ref-parser";
+import { bundle, Config } from "@redocly/openapi-core";
+import type { Source, Document } from "@redocly/openapi-core";
+import { ResolvedConfig } from "@redocly/openapi-core/lib/config";
+import chalk from "chalk";
+// @ts-ignore
+import { convertObj } from "swagger2openapi";
+
+import { OpenApiObject } from "../types";
+
+function serializer(replacer: any, cycleReplacer: any) {
+  var stack: any = [],
+    keys: any = [];
+
+  if (cycleReplacer === undefined)
+    cycleReplacer = function (key: any, value: any) {
+      if (stack[0] === value) return "circular()";
+      return value.title ? `circular(${value.title})` : "circular()";
+    };
+
+  return function (key: any, value: any) {
+    if (stack.length > 0) {
+      // @ts-ignore
+      var thisPos = stack.indexOf(this);
+      // @ts-ignore
+      ~thisPos ? stack.splice(thisPos + 1) : stack.push(this);
+      ~thisPos ? keys.splice(thisPos, Infinity, key) : keys.push(key);
+      // @ts-ignore
+      if (~stack.indexOf(value)) value = cycleReplacer.call(this, key, value);
+    } else stack.push(value);
+
+    // @ts-ignore
+    return replacer === undefined ? value : replacer.call(this, key, value);
+  };
+}
+
+export function convertSwagger2OpenAPI(spec: object) {
+  console.warn(
+    "[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0"
+  );
+  return new Promise((resolve, reject) =>
+    convertObj(
+      spec,
+      { patch: true, warnOnly: true, text: "{}", anchors: true },
+      (err: any, res: any) => {
+        // TODO: log any warnings
+        if (err) {
+          return reject(err);
+        }
+        resolve(res && res.openapi);
+      }
+    )
+  );
+}
+
+async function resolveJsonRefs(specUrlOrObject: object | string) {
+  try {
+    let schema = await $RefParser.dereference(specUrlOrObject, {
+      continueOnError: true,
+      resolve: {
+        file: true,
+        external: true,
+        http: {
+          timeout: 15000, // 15 sec timeout
+        },
+      },
+      dereference: {
+        circular: true,
+      },
+    });
+    return schema as OpenApiObject;
+  } catch (err: any) {
+    console.error(chalk.yellow(err.errors[0]?.message ?? err));
+    return;
+  }
+}
+
+export async function loadAndResolveSpec(specUrlOrObject: object | string) {
+  const config = new Config({} as ResolvedConfig);
+  const bundleOpts = {
+    config,
+    base: process.cwd(),
+  } as any;
+
+  if (typeof specUrlOrObject === "object" && specUrlOrObject !== null) {
+    bundleOpts["doc"] = {
+      source: { absoluteRef: "" } as Source,
+      parsed: specUrlOrObject,
+    } as Document;
+  } else {
+    bundleOpts["ref"] = specUrlOrObject;
+  }
+
+  // Force dereference ?
+  // bundleOpts["dereference"] = true;
+
+  const {
+    bundle: { parsed },
+  } = await bundle(bundleOpts);
+  const resolved = await resolveJsonRefs(parsed);
+
+  // Force serialization and replace circular $ref pointers
+  // @ts-ignore
+  const serialized = JSON.stringify(resolved, serializer());
+  let decycled;
+  try {
+    decycled = JSON.parse(serialized);
+  } catch (err: any) {
+    console.error(chalk.yellow(err));
+  }
+  return decycled !== undefined && typeof decycled === "object"
+    ? decycled.swagger !== undefined
+      ? convertSwagger2OpenAPI(decycled)
+      : decycled
+    : resolved;
+}