docusaurus-plugin-openapi-docs 0.0.0-1000

package/src/markdown/utils.ts

@@ -0,0 +1,89 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+/**
+ * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
+ * It is designed for rendering HTML a strings.
+ */
+export type Children = string | undefined | (string | string[] | undefined)[];
+
+export type Props = Record<string, any> & { children?: Children };
+
+export type Options = { inline?: boolean };
+
+export function create(
+  tag: string,
+  props: Props,
+  options: Options = {}
+): string {
+  const { children, ...rest } = props;
+
+  let propString = "";
+  for (const [key, value] of Object.entries(rest)) {
+    propString += `\n  ${key}={${JSON.stringify(value)}}`;
+  }
+  let indentedChildren = render(children).replace(/^/gm, "  ");
+
+  if (options.inline) {
+    propString += `\n  children={${JSON.stringify(children)}}`;
+    indentedChildren = "";
+  }
+
+  propString += propString ? "\n" : "";
+  indentedChildren += indentedChildren ? "\n" : "";
+  return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
+}
+
+export function guard<T>(
+  value: T | undefined,
+  cb: (value: T) => Children
+): string {
+  if (!!value || value === 0) {
+    const children = cb(value);
+    return render(children);
+  }
+  return "";
+}
+
+export function render(children: Children): string {
+  if (Array.isArray(children)) {
+    const filteredChildren = children.filter((c) => c !== undefined);
+    return filteredChildren
+      .map((i: any) => (Array.isArray(i) ? i.join("") : i))
+      .join("");
+  }
+  return children ?? "";
+}
+
+// Regex to selectively URL-encode '>' and '<' chars
+export const lessThan =
+  /<=?(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
+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

@@ -0,0 +1,49 @@
+openapi: 3.0.3
+info:
+  title: YAML Example
+  version: 1.0.0
+  description: Sample description.
+paths:
+  /hello:
+    get:
+      summary: Hello World
+      description: Example OpenApi definition with YAML.
+      responses:
+        200:
+          description: OK
+
+tags:
+  - name: tag1
+    description: Everything about your Pets
+    x-displayName: Tag 1
+  - name: tag2
+    description: Tag 2 description
+    x-displayName: Tag 2
+  - name: tag3
+    description: Tag 3 description
+    x-displayName: Tag 3
+  - name: tag4
+    description: Tag 4 description
+    x-displayName: Tag 4
+
+x-tagGroups:
+  - name: Tag 1 & 2
+    tags:
+      - tag1
+      - tag2
+  - name: Trinity
+    tags:
+      - tag1
+      - tag2
+      - tag3
+  - name: Last Two
+    tags:
+      - tag3
+      - tag4
+
+components:
+  schemas:
+    HelloString:
+      x-tags:
+        - tag1
+      type: string

package/src/openapi/createRequestExample.ts

@@ -0,0 +1,235 @@
+/* ============================================================================
+ * 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 chalk from "chalk";
+import merge from "lodash/merge";
+
+import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
+
+interface OASTypeToTypeMap {
+  string: string;
+  number: number;
+  integer: number;
+  boolean: boolean;
+  object: any;
+  array: any[];
+}
+
+type Primitives = {
+  [OASType in keyof OASTypeToTypeMap]: {
+    [format: string]: (schema: SchemaObject) => OASTypeToTypeMap[OASType];
+  };
+};
+
+const primitives: Primitives = {
+  string: {
+    default: () => "string",
+    email: () => "user@example.com",
+    date: () => "2024-07-29",
+    "date-time": () => "2024-07-29T15:51:28.071Z",
+    uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    hostname: () => "example.com",
+    ipv4: () => "198.51.100.42",
+    ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
+  },
+  number: {
+    default: () => 0,
+    float: () => 0.0,
+  },
+  integer: {
+    default: () => 0,
+  },
+  boolean: {
+    default: (schema) =>
+      typeof schema.default === "boolean" ? schema.default : true,
+  },
+  object: {},
+  array: {},
+};
+
+function sampleRequestFromProp(name: string, prop: any, obj: any): any {
+  // Handle resolved circular props
+  if (typeof prop === "object" && Object.keys(prop).length === 0) {
+    obj[name] = prop;
+    return obj;
+  }
+
+  // TODO: handle discriminators
+
+  if (prop.oneOf) {
+    obj[name] = sampleRequestFromSchema(prop.oneOf[0]);
+  } else if (prop.anyOf) {
+    obj[name] = sampleRequestFromSchema(prop.anyOf[0]);
+  } else if (prop.allOf) {
+    const mergedSchemas = mergeAllOf(prop) as SchemaObject;
+    sampleRequestFromProp(name, mergedSchemas, obj);
+  } else {
+    obj[name] = sampleRequestFromSchema(prop);
+  }
+  return obj;
+}
+
+export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
+  try {
+    // deep copy schema before processing
+    let schemaCopy = JSON.parse(JSON.stringify(schema));
+    let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
+
+    if (example !== undefined) {
+      return example;
+    }
+
+    if (oneOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, oneOf[0]);
+        delete combinedSchemas.oneOf;
+        return sampleRequestFromSchema(combinedSchemas);
+      }
+      // Just go with first schema
+      return sampleRequestFromSchema(oneOf[0]);
+    }
+
+    if (anyOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, anyOf[0]);
+        delete combinedSchemas.anyOf;
+        return sampleRequestFromSchema(combinedSchemas);
+      }
+      // Just go with first schema
+      return sampleRequestFromSchema(anyOf[0]);
+    }
+
+    if (allOf) {
+      const mergedSchemas = mergeAllOf(schemaCopy) as SchemaObject;
+      if (mergedSchemas.properties) {
+        for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+          if ((value.readOnly && value.readOnly === true) || value.deprecated) {
+            delete mergedSchemas.properties[key];
+          }
+        }
+      }
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, mergedSchemas);
+        delete combinedSchemas.allOf;
+        return sampleRequestFromSchema(combinedSchemas);
+      }
+      return sampleRequestFromSchema(mergedSchemas);
+    }
+
+    if (!type) {
+      if (properties) {
+        type = "object";
+      } else if (items) {
+        type = "array";
+      } else {
+        return;
+      }
+    }
+
+    if (type === "object") {
+      let obj: any = {};
+      for (let [name, prop] of Object.entries(properties ?? {}) as any) {
+        if (prop.properties) {
+          for (const [key, value] of Object.entries(prop.properties) as any) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
+              delete prop.properties[key];
+            }
+          }
+        }
+
+        if (prop.items && prop.items.properties) {
+          for (const [key, value] of Object.entries(
+            prop.items.properties
+          ) as any) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
+              delete prop.items.properties[key];
+            }
+          }
+        }
+
+        if (prop.readOnly && prop.readOnly === true) {
+          continue;
+        }
+
+        if (prop.deprecated) {
+          continue;
+        }
+
+        // Resolve schema from prop recursively
+        obj = sampleRequestFromProp(name, prop, obj);
+      }
+      return obj;
+    }
+
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return items?.anyOf.map((item: any) => sampleRequestFromSchema(item));
+      }
+
+      if (Array.isArray(items?.oneOf)) {
+        return items?.oneOf.map((item: any) => sampleRequestFromSchema(item));
+      }
+
+      return normalizeArray(sampleRequestFromSchema(items));
+    }
+
+    if (schemaCopy.enum) {
+      if (schemaCopy.default) {
+        return schemaCopy.default;
+      }
+      return normalizeArray(schemaCopy.enum)[0];
+    }
+
+    if (
+      (schema.readOnly && schema.readOnly === true) ||
+      schemaCopy.deprecated
+    ) {
+      return undefined;
+    }
+
+    return primitive(schemaCopy);
+  } catch (err) {
+    console.error(
+      chalk.yellow("WARNING: failed to create example from schema object:", err)
+    );
+    return;
+  }
+};
+
+function primitive(schema: SchemaObject = {}) {
+  let { type, format } = schema;
+
+  if (type === undefined) {
+    return;
+  }
+
+  let fn = schema.default ? () => schema.default : primitives[type].default;
+
+  if (format !== undefined) {
+    fn = primitives[type][format] || fn;
+  }
+
+  if (fn) {
+    return fn(schema);
+  }
+
+  return "Unknown Type: " + schema.type;
+}
+
+function normalizeArray(arr: any) {
+  if (Array.isArray(arr)) {
+    return arr;
+  }
+  return [arr];
+}

package/src/openapi/createResponseExample.ts

@@ -0,0 +1,238 @@
+/* ============================================================================
+ * 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 chalk from "chalk";
+import merge from "lodash/merge";
+
+import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
+
+interface OASTypeToTypeMap {
+  string: string;
+  number: number;
+  integer: number;
+  boolean: boolean;
+  object: any;
+  array: any[];
+}
+
+type Primitives = {
+  [OASType in keyof OASTypeToTypeMap]: {
+    [format: string]: (schema: SchemaObject) => OASTypeToTypeMap[OASType];
+  };
+};
+
+const primitives: Primitives = {
+  string: {
+    default: () => "string",
+    email: () => "user@example.com",
+    date: () => "2024-07-29",
+    "date-time": () => "2024-07-29T15:51:28.071Z",
+    uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    hostname: () => "example.com",
+    ipv4: () => "198.51.100.42",
+    ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
+  },
+  number: {
+    default: () => 0,
+    float: () => 0.0,
+  },
+  integer: {
+    default: () => 0,
+  },
+  boolean: {
+    default: (schema) =>
+      typeof schema.default === "boolean" ? schema.default : true,
+  },
+  object: {},
+  array: {},
+};
+
+function sampleResponseFromProp(name: string, prop: any, obj: any): any {
+  // Handle resolved circular props
+  if (typeof prop === "object" && Object.keys(prop).length === 0) {
+    obj[name] = prop;
+    return obj;
+  }
+
+  // TODO: handle discriminators
+
+  if (prop.oneOf) {
+    obj[name] = sampleResponseFromSchema(prop.oneOf[0]);
+  } else if (prop.anyOf) {
+    obj[name] = sampleResponseFromSchema(prop.anyOf[0]);
+  } else if (prop.allOf) {
+    const mergedSchemas = mergeAllOf(prop) as SchemaObject;
+    sampleResponseFromProp(name, mergedSchemas, obj);
+  } else {
+    obj[name] = sampleResponseFromSchema(prop);
+  }
+  return obj;
+}
+
+export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
+  try {
+    // deep copy schema before processing
+    let schemaCopy = JSON.parse(JSON.stringify(schema));
+    let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
+
+    if (example !== undefined) {
+      return example;
+    }
+
+    if (allOf) {
+      const mergedSchemas = mergeAllOf(schemaCopy) as SchemaObject;
+      if (mergedSchemas.properties) {
+        for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+          if (
+            (value.writeOnly && value.writeOnly === true) ||
+            value.deprecated
+          ) {
+            delete mergedSchemas.properties[key];
+          }
+        }
+      }
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, mergedSchemas);
+        delete combinedSchemas.allOf;
+        return sampleResponseFromSchema(combinedSchemas);
+      }
+      return sampleResponseFromSchema(mergedSchemas);
+    }
+
+    if (oneOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, oneOf[0]);
+        delete combinedSchemas.oneOf;
+        return sampleResponseFromSchema(combinedSchemas);
+      }
+      // Just go with first schema
+      return sampleResponseFromSchema(oneOf[0]);
+    }
+
+    if (anyOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, anyOf[0]);
+        delete combinedSchemas.anyOf;
+        return sampleResponseFromSchema(combinedSchemas);
+      }
+      // Just go with first schema
+      return sampleResponseFromSchema(anyOf[0]);
+    }
+
+    if (!type) {
+      if (properties) {
+        type = "object";
+      } else if (items) {
+        type = "array";
+      } else {
+        return;
+      }
+    }
+
+    if (type === "object") {
+      let obj: any = {};
+      for (let [name, prop] of Object.entries(properties ?? {}) as any) {
+        if (prop.properties) {
+          for (const [key, value] of Object.entries(prop.properties) as any) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
+              delete prop.properties[key];
+            }
+          }
+        }
+
+        if (prop.items && prop.items.properties) {
+          for (const [key, value] of Object.entries(
+            prop.items.properties
+          ) as any) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
+              delete prop.items.properties[key];
+            }
+          }
+        }
+
+        if (prop.writeOnly && prop.writeOnly === true) {
+          continue;
+        }
+
+        if (prop.deprecated) {
+          continue;
+        }
+
+        // Resolve schema from prop recursively
+        obj = sampleResponseFromProp(name, prop, obj);
+      }
+      return obj;
+    }
+
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return items?.anyOf.map((item: any) => sampleResponseFromSchema(item));
+      }
+
+      if (Array.isArray(items?.oneOf)) {
+        return items?.oneOf.map((item: any) => sampleResponseFromSchema(item));
+      }
+
+      return [sampleResponseFromSchema(items)];
+    }
+
+    if (schemaCopy.enum) {
+      if (schemaCopy.default) {
+        return schemaCopy.default;
+      }
+      return normalizeArray(schemaCopy.enum)[0];
+    }
+
+    if (
+      (schemaCopy.writeOnly && schemaCopy.writeOnly === true) ||
+      schemaCopy.deprecated
+    ) {
+      return undefined;
+    }
+
+    return primitive(schemaCopy);
+  } catch (err) {
+    console.error(
+      chalk.yellow("WARNING: failed to create example from schema object:", err)
+    );
+    return;
+  }
+};
+
+function primitive(schema: SchemaObject = {}) {
+  let { type, format } = schema;
+
+  if (type === undefined) {
+    return;
+  }
+
+  let fn = schema.default ? () => schema.default : primitives[type].default;
+
+  if (format !== undefined) {
+    fn = primitives[type][format] || fn;
+  }
+
+  if (fn) {
+    return fn(schema);
+  }
+
+  return "Unknown Type: " + schema.type;
+}
+
+function normalizeArray(arr: any) {
+  if (Array.isArray(arr)) {
+    return arr;
+  }
+  return [arr];
+}

package/src/openapi/index.ts

@@ -0,0 +1,8 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+export { readOpenapiFiles, processOpenapiFiles } from "./openapi";

package/src/openapi/openapi.test.ts

@@ -0,0 +1,40 @@
+/* ============================================================================
+ * 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 path from "path";
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { posixPath } from "@docusaurus/utils";
+
+import { readOpenapiFiles } from ".";
+
+// npx jest packages/docusaurus-plugin-openapi/src/openapi/openapi.test.ts --watch
+
+describe("openapi", () => {
+  describe("readOpenapiFiles", () => {
+    it("readOpenapiFiles", async () => {
+      const results = await readOpenapiFiles(
+        posixPath(path.join(__dirname, "__fixtures__/examples"))
+      );
+      const categoryMeta = results.find((x) =>
+        x.source.endsWith("_category_.json")
+      );
+      expect(categoryMeta).toBeFalsy();
+      // console.log(results);
+      const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
+      expect(yaml).toBeTruthy();
+      expect(yaml?.sourceDirName).toBe(".");
+
+      expect(yaml?.data.tags).toBeDefined();
+      expect(yaml?.data["x-tagGroups"]).toBeDefined();
+
+      expect(
+        yaml?.data.components?.schemas?.HelloString["x-tags"]
+      ).toBeDefined();
+    });
+  });
+});