docusaurus-plugin-openapi-docs 1.0.0

package/src/markdown/createStatusCodes.ts

@@ -0,0 +1,52 @@
+/* ============================================================================
+ * 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 { ApiItem } from "../types";
+import { createDescription } from "./createDescription";
+import { createSchemaDetails } from "./createSchemaDetails";
+import { create } from "./utils";
+
+interface Props {
+  responses: ApiItem["responses"];
+}
+
+export function createStatusCodes({ responses }: Props) {
+  if (responses === undefined) {
+    return undefined;
+  }
+
+  const codes = Object.keys(responses);
+  if (codes.length === 0) {
+    return undefined;
+  }
+
+  return create("div", {
+    children: [
+      create("Tabs", {
+        children: codes.map((code) => {
+          return create("TabItem", {
+            label: code,
+            value: code,
+            children: [
+              create("div", {
+                children: createDescription(responses[code].description),
+              }),
+              create("div", {
+                children: createSchemaDetails({
+                  title: "Schema",
+                  body: {
+                    content: responses[code].content,
+                  },
+                }),
+              }),
+            ],
+          });
+        }),
+      }),
+    ],
+  });
+}

package/src/markdown/createVersionBadge.ts

@@ -0,0 +1,18 @@
+/* ============================================================================
+ * 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 { 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)}`,
+    }),
+    `\n\n`,
+  ]);
+}

package/src/markdown/index.ts

@@ -0,0 +1,55 @@
+/* ============================================================================
+ * 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 { escape } from "lodash";
+
+import { ApiPageMetadata, InfoPageMetadata } from "../types";
+import { createDeprecationNotice } from "./createDeprecationNotice";
+import { createDescription } from "./createDescription";
+import { createParamsDetails } from "./createParamsDetails";
+import { createRequestBodyDetails } from "./createRequestBodyDetails";
+import { createStatusCodes } from "./createStatusCodes";
+import { createVersionBadge } from "./createVersionBadge";
+import { render } from "./utils";
+
+export function createApiPageMD({
+  title,
+  api: {
+    deprecated,
+    "x-deprecated-description": deprecatedDescription,
+    description,
+    parameters,
+    requestBody,
+    responses,
+  },
+}: ApiPageMetadata) {
+  return render([
+    `import ParamsItem from "@theme/ParamsItem";\n`,
+    `import SchemaItem from "@theme/SchemaItem"\n`,
+    `import Tabs from "@theme/Tabs";\n`,
+    `import TabItem from "@theme/TabItem";\n\n`,
+    `## ${escape(title)}\n\n`,
+    createDeprecationNotice({ deprecated, description: deprecatedDescription }),
+    createDescription(escape(description)),
+    createParamsDetails({ parameters, type: "path" }),
+    createParamsDetails({ parameters, type: "query" }),
+    createParamsDetails({ parameters, type: "header" }),
+    createParamsDetails({ parameters, type: "cookie" }),
+    createRequestBodyDetails({ title: "Request Body", body: requestBody }),
+    createStatusCodes({ responses }),
+  ]);
+}
+
+export function createInfoPageMD({
+  info: { title, version, description },
+}: InfoPageMetadata) {
+  return render([
+    createVersionBadge(version),
+    `# ${escape(title)}\n\n`,
+    createDescription(description),
+  ]);
+}

package/src/markdown/schema.test.ts

@@ -0,0 +1,196 @@
+/* ============================================================================
+ * 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 { getQualifierMessage } from "./schema";
+
+describe("getQualifierMessage", () => {
+  it("should render nothing", () => {
+    const actual = getQualifierMessage({});
+    expect(actual).toBeUndefined();
+  });
+
+  //
+  // minLength + maxLength
+  //
+  it("should render minLength", () => {
+    const expected = "**Possible values:** 1 ≤ length";
+    const actual = getQualifierMessage({ minLength: 1 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render maxLength", () => {
+    const expected = "**Possible values:** length ≤ 40";
+    const actual = getQualifierMessage({ maxLength: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minLength and maxLength", () => {
+    const expected = "**Possible values:** 1 ≤ length ≤ 40";
+    const actual = getQualifierMessage({ minLength: 1, maxLength: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  //
+  // pattern
+  //
+  it("should render pattern", () => {
+    const expected =
+      "**Possible values:** Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+    const actual = getQualifierMessage({ pattern: "^[a-zA-Z0-9_-]*$" });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render multiple string qualifiers", () => {
+    const expected =
+      "**Possible values:** 1 ≤ length ≤ 40, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+    const actual = getQualifierMessage({
+      minLength: 1,
+      maxLength: 40,
+      pattern: "^[a-zA-Z0-9_-]*$",
+    });
+    expect(actual).toBe(expected);
+  });
+
+  //
+  // enum
+  //
+  it("should render enum", () => {
+    const expected = "**Possible values:** [`cat`, `dog`, `mouse`]";
+    const actual = getQualifierMessage({ enum: ["cat", "dog", "mouse"] });
+    expect(actual).toBe(expected);
+  });
+
+  //
+  // minimum + maximum + exclusiveMinimum + exclusiveMaximum
+  //
+  it("should render minimum", () => {
+    const expected = "**Possible values:** 1 ≤ value";
+    const actual = getQualifierMessage({ minimum: 1 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render maximum", () => {
+    const expected = "**Possible values:** value ≤ 40";
+    const actual = getQualifierMessage({ maximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render numeric exclusiveMinimum", () => {
+    const expected = "**Possible values:** 1 < value";
+    const actual = getQualifierMessage({ exclusiveMinimum: 1 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render numeric exclusiveMaximum", () => {
+    const expected = "**Possible values:** value < 40";
+    const actual = getQualifierMessage({ exclusiveMaximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render boolean exclusiveMinimum", () => {
+    const expected = "**Possible values:** 1 < value";
+    const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: true });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render boolean exclusiveMaximum", () => {
+    const expected = "**Possible values:** value < 40";
+    const actual = getQualifierMessage({ maximum: 40, exclusiveMaximum: true });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum when exclusiveMinimum is false", () => {
+    const expected = "**Possible values:** 1 ≤ value";
+    const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: false });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render maximum when exclusiveMaximum is false", () => {
+    const expected = "**Possible values:** value ≤ 40";
+    const actual = getQualifierMessage({
+      maximum: 40,
+      exclusiveMaximum: false,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum and maximum", () => {
+    const expected = "**Possible values:** 1 ≤ value ≤ 40";
+    const actual = getQualifierMessage({ minimum: 1, maximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render boolean exclusiveMinimum and maximum", () => {
+    const expected = "**Possible values:** 1 < value ≤ 40";
+    const actual = getQualifierMessage({
+      minimum: 1,
+      maximum: 40,
+      exclusiveMinimum: true,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum and boolean exclusiveMaximum", () => {
+    const expected = "**Possible values:** 1 ≤ value < 40";
+    const actual = getQualifierMessage({
+      minimum: 1,
+      maximum: 40,
+      exclusiveMaximum: true,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render numeric exclusiveMinimum and maximum", () => {
+    const expected = "**Possible values:** 1 < value ≤ 40";
+    const actual = getQualifierMessage({
+      exclusiveMinimum: 1,
+      maximum: 40,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum and numeric exclusiveMaximum", () => {
+    const expected = "**Possible values:** 1 ≤ value < 40";
+    const actual = getQualifierMessage({
+      minimum: 1,
+      exclusiveMaximum: 40,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
+    const expected = "**Possible values:** 1 < value < 40";
+    const actual = getQualifierMessage({
+      exclusiveMinimum: 1,
+      maximum: 40,
+      exclusiveMaximum: true,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render nothing with empty boolean exclusiveMinimum", () => {
+    const actual = getQualifierMessage({
+      exclusiveMinimum: true,
+    });
+    expect(actual).toBeUndefined();
+  });
+
+  it("should render nothing with empty boolean exclusiveMaximum", () => {
+    const actual = getQualifierMessage({
+      exclusiveMaximum: true,
+    });
+    expect(actual).toBeUndefined();
+  });
+
+  it("should render nothing with empty boolean exclusiveMinimum and exclusiveMaximum", () => {
+    const actual = getQualifierMessage({
+      exclusiveMinimum: true,
+      exclusiveMaximum: true,
+    });
+    expect(actual).toBeUndefined();
+  });
+});

package/src/markdown/schema.ts

@@ -0,0 +1,115 @@
+/* ============================================================================
+ * 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 { 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) {
+    return "object";
+  }
+
+  if (schema.type === "object") {
+    return schema.xml?.name ?? schema.type;
+  }
+
+  return schema.title ?? schema.type;
+}
+
+export function getSchemaName(
+  schema: SchemaObject,
+  circular?: boolean
+): string {
+  if (schema.items) {
+    return prettyName(schema.items, circular) + "[]";
+  }
+
+  return prettyName(schema, circular) ?? "";
+}
+
+export function getQualifierMessage(schema?: SchemaObject): string | undefined {
+  // TODO:
+  // - maxItems
+  // - minItems
+  // - uniqueItems
+  // - maxProperties
+  // - minProperties
+  // - multipleOf
+  if (!schema) {
+    return undefined;
+  }
+
+  if (schema.items) {
+    return getQualifierMessage(schema.items);
+  }
+
+  let message = "**Possible values:** ";
+
+  let qualifierGroups = [];
+
+  if (schema.minLength || schema.maxLength) {
+    let lengthQualifier = "";
+    if (schema.minLength) {
+      lengthQualifier += `${schema.minLength} ≤ `;
+    }
+    lengthQualifier += "length";
+    if (schema.maxLength) {
+      lengthQualifier += ` ≤ ${schema.maxLength}`;
+    }
+    qualifierGroups.push(lengthQualifier);
+  }
+
+  if (
+    schema.minimum ||
+    schema.maximum ||
+    typeof schema.exclusiveMinimum === "number" ||
+    typeof schema.exclusiveMaximum === "number"
+  ) {
+    let minmaxQualifier = "";
+    if (typeof schema.exclusiveMinimum === "number") {
+      minmaxQualifier += `${schema.exclusiveMinimum} < `;
+    } else if (schema.minimum && !schema.exclusiveMinimum) {
+      minmaxQualifier += `${schema.minimum} ≤ `;
+    } else if (schema.minimum && schema.exclusiveMinimum === true) {
+      minmaxQualifier += `${schema.minimum} < `;
+    }
+    minmaxQualifier += "value";
+    if (typeof schema.exclusiveMaximum === "number") {
+      minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+    } else if (schema.maximum && !schema.exclusiveMaximum) {
+      minmaxQualifier += ` ≤ ${schema.maximum}`;
+    } else if (schema.maximum && schema.exclusiveMaximum === true) {
+      minmaxQualifier += ` < ${schema.maximum}`;
+    }
+    qualifierGroups.push(minmaxQualifier);
+  }
+
+  if (schema.pattern) {
+    qualifierGroups.push(
+      `Value must match regular expression \`${schema.pattern}\``
+    );
+  }
+
+  if (schema.enum) {
+    qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
+  if (qualifierGroups.length === 0) {
+    return undefined;
+  }
+
+  return message + qualifierGroups.join(", ");
+}

package/src/markdown/utils.ts

@@ -0,0 +1,39 @@
+/* ============================================================================
+ * 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 type Children = string | undefined | (string | undefined)[];
+
+export type Props = Record<string, any> & { children?: Children };
+
+export function create(tag: string, props: Props): string {
+  const { children, ...rest } = props;
+
+  let propString = "";
+  for (const [key, value] of Object.entries(rest)) {
+    propString += ` ${key}={${JSON.stringify(value)}}`;
+  }
+
+  return `<${tag}${propString}>${render(children)}</${tag}>`;
+}
+
+export function guard<T>(
+  value: T | undefined,
+  cb: (value: T) => Children
+): string {
+  if (value) {
+    const children = cb(value);
+    return render(children);
+  }
+  return "";
+}
+
+export function render(children: Children): string {
+  if (Array.isArray(children)) {
+    return children.filter((c) => c !== undefined).join("");
+  }
+  return children ?? "";
+}

package/src/openapi/__fixtures__/examples/openapi.yaml

@@ -0,0 +1,13 @@
+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

package/src/openapi/__fixtures__/examples/yogurtstore/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Foods",
+  "collapsed": true
+}

package/src/openapi/__fixtures__/examples/yogurtstore/froyo.yaml

@@ -0,0 +1,13 @@
+openapi: 3.0.3
+info:
+  title: Frozen Yogurt Example
+  version: 1.0.0
+  description: Sample description.
+paths:
+  /flavors:
+    get:
+      summary: List All Flavors
+      description: Froyo's the best!
+      responses:
+        200:
+          description: OK

package/src/openapi/__fixtures__/examples/yogurtstore/nested/nested.yaml

@@ -0,0 +1,13 @@
+openapi: 3.0.3
+info:
+  title: Nested Folder Example
+  version: 1.0.0
+  description: Sample description.
+paths:
+  /flavors:
+    get:
+      summary: List All
+      description: All
+      responses:
+        200:
+          description: OK

package/src/openapi/createExample.ts

@@ -0,0 +1,143 @@
+/* ============================================================================
+ * 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 { SchemaObject } from "./types";
+
+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: () => new Date().toISOString().substring(0, 10),
+    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: {},
+};
+
+export const sampleFromSchema = (schema: SchemaObject = {}): any => {
+  let { type, example, allOf, properties, items } = schema;
+
+  if (example !== undefined) {
+    return example;
+  }
+
+  if (allOf) {
+    // TODO: We are just assuming it will always be an object for now
+    let obj: SchemaObject = {
+      type: "object",
+      properties: {},
+      required: [], // NOTE: We shouldn't need to worry about required
+    };
+    for (let item of allOf) {
+      if (item.properties) {
+        obj.properties = {
+          ...obj.properties,
+          ...item.properties,
+        };
+      }
+    }
+    return sampleFromSchema(obj);
+  }
+
+  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 ?? {})) {
+      if (prop.deprecated) {
+        continue;
+      }
+      obj[name] = sampleFromSchema(prop);
+    }
+    return obj;
+  }
+
+  if (type === "array") {
+    if (Array.isArray(items?.anyOf)) {
+      return items?.anyOf.map((item) => sampleFromSchema(item));
+    }
+
+    if (Array.isArray(items?.oneOf)) {
+      return items?.oneOf.map((item) => sampleFromSchema(item));
+    }
+
+    return [sampleFromSchema(items)];
+  }
+
+  if (schema.enum) {
+    if (schema.default) {
+      return schema.default;
+    }
+    return normalizeArray(schema.enum)[0];
+  }
+
+  return primitive(schema);
+};
+
+function primitive(schema: SchemaObject = {}) {
+  let { type, format } = schema;
+
+  if (type === undefined) {
+    return;
+  }
+
+  let fn = 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";