@camunda8/docusaurus-plugin-openapi-docs 4.5.1

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/__fixtures__/webhook/openapi.yaml

@@ -0,0 +1,17 @@
+openapi: 3.0.3
+info:
+  title: Webhook Example
+  version: 1.0.0
+paths: {}
+webhooks:
+  order.created:
+    post:
+      requestBody:
+        description: example body
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        "200":
+          description: OK

package/src/openapi/createRequestExample.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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 { sampleFromSchema } from "./createSchemaExample";
+import { SchemaObject } from "./types";
+
+export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
+  return sampleFromSchema(schema, { type: "request" });
+};

package/src/openapi/createResponseExample.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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 { sampleFromSchema } from "./createSchemaExample";
+import { SchemaObject } from "./types";
+
+export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
+  return sampleFromSchema(schema, { type: "response" });
+};

package/src/openapi/createSchemaExample.ts

@@ -0,0 +1,292 @@
+/* ============================================================================
+ * 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[];
+  null: string | null;
+}
+
+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: {},
+  null: {
+    default: () => "null",
+  },
+};
+
+type ExampleType = "request" | "response";
+
+interface ExampleContext {
+  type: ExampleType;
+}
+
+function shouldExcludeProperty(
+  prop: SchemaObject,
+  context: ExampleContext
+): boolean {
+  if (prop.deprecated) {
+    return true;
+  }
+
+  if (context.type === "request") {
+    return prop.readOnly === true;
+  } else {
+    return prop.writeOnly === true;
+  }
+}
+
+function sampleFromProp(
+  name: string,
+  prop: any,
+  obj: any,
+  context: ExampleContext
+): 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] = sampleFromSchema(prop.oneOf[0], context);
+  } else if (prop.anyOf) {
+    obj[name] = sampleFromSchema(prop.anyOf[0], context);
+  } else if (prop.allOf) {
+    const mergedSchemas = mergeAllOf(prop) as SchemaObject;
+    sampleFromProp(name, mergedSchemas, obj, context);
+  } else {
+    obj[name] = sampleFromSchema(prop, context);
+  }
+  return obj;
+}
+
+export const sampleFromSchema = (
+  schema: SchemaObject = {},
+  context: ExampleContext
+): 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 sampleFromSchema(combinedSchemas, context);
+      }
+      // Just go with first schema
+      return sampleFromSchema(oneOf[0], context);
+    }
+
+    if (anyOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, anyOf[0]);
+        delete combinedSchemas.anyOf;
+        return sampleFromSchema(combinedSchemas, context);
+      }
+      // Just go with first schema
+      return sampleFromSchema(anyOf[0], context);
+    }
+
+    if (allOf) {
+      const mergedSchemas = mergeAllOf(schemaCopy) as SchemaObject;
+      if (mergedSchemas.properties) {
+        for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+          if (shouldExcludeProperty(value, context)) {
+            delete mergedSchemas.properties[key];
+          }
+        }
+      }
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, mergedSchemas);
+        delete combinedSchemas.allOf;
+        return sampleFromSchema(combinedSchemas, context);
+      }
+      return sampleFromSchema(mergedSchemas, context);
+    }
+
+    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 (shouldExcludeProperty(value, context)) {
+              delete prop.properties[key];
+            }
+          }
+        }
+
+        if (prop.items && prop.items.properties) {
+          for (const [key, value] of Object.entries(
+            prop.items.properties
+          ) as any) {
+            if (shouldExcludeProperty(value, context)) {
+              delete prop.items.properties[key];
+            }
+          }
+        }
+
+        if (shouldExcludeProperty(prop, context)) {
+          continue;
+        }
+
+        // Resolve schema from prop recursively
+        obj = sampleFromProp(name, prop, obj, context);
+      }
+      return obj;
+    }
+
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return processArrayItems(items, "anyOf", context);
+      }
+
+      if (Array.isArray(items?.oneOf)) {
+        return processArrayItems(items, "oneOf", context);
+      }
+
+      return normalizeArray(sampleFromSchema(items, context));
+    }
+
+    if (schemaCopy.enum) {
+      if (schemaCopy.default) {
+        return schemaCopy.default;
+      }
+      return normalizeArray(schemaCopy.enum)[0];
+    }
+
+    if (shouldExcludeProperty(schemaCopy, context)) {
+      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;
+  }
+
+  // If type is an array, use the first type
+  if (Array.isArray(type)) {
+    type = type[0];
+    if (type === undefined) {
+      return;
+    }
+  }
+
+  // Use schema default if available, otherwise use type default
+  if (schema.default !== undefined) {
+    return schema.default;
+  }
+
+  const typeConfig = primitives[type];
+  if (typeConfig) {
+    if (format !== undefined && typeConfig[format] !== undefined) {
+      return typeConfig[format](schema);
+    }
+    if (typeConfig.default !== undefined) {
+      return typeConfig.default(schema);
+    }
+  }
+
+  return "Unknown Type: " + schema.type;
+}
+
+function normalizeArray(arr: any) {
+  if (Array.isArray(arr)) {
+    return arr;
+  }
+  return [arr];
+}
+
+function processArrayItems(
+  items: SchemaObject,
+  schemaType: "anyOf" | "oneOf",
+  context: ExampleContext
+): any[] {
+  const itemsArray = items[schemaType] as SchemaObject[];
+  return itemsArray.map((item: SchemaObject) => {
+    // If items has properties, merge them with each item
+    if (items.properties) {
+      const combinedSchema = {
+        ...item,
+        properties: {
+          ...items.properties, // Common properties from parent
+          ...item.properties, // Specific properties from this anyOf/oneOf item
+        },
+      };
+      // Remove anyOf/oneOf to prevent infinite recursion when calling sampleFromSchema
+      delete combinedSchema[schemaType];
+      return sampleFromSchema(combinedSchema, context);
+    }
+    return sampleFromSchema(item, context);
+  });
+}

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();
+    });
+  });
+});