docusaurus-plugin-openapi-docs 0.0.0-1000

package/src/markdown/createStatusCodes.ts

@@ -0,0 +1,63 @@
+/* ============================================================================
+ * 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 } from "./utils";
+import { ApiItem } from "../types";
+
+export default function json2xml(o: any, tab: any) {
+  var toXml = function (v: any, name: string, ind: any) {
+      var xml = "";
+      if (v instanceof Array) {
+        for (var i = 0, n = v.length; i < n; i++)
+          xml += ind + toXml(v[i], name, ind + "\t") + "\n";
+      } else if (typeof v == "object") {
+        var hasChild = false;
+        xml += ind + "<" + name;
+        for (var m in v) {
+          if (m.charAt(0) === "@")
+            xml += " " + m.substr(1) + '="' + v[m].toString() + '"';
+          else hasChild = true;
+        }
+        xml += hasChild ? ">" : "/>";
+        if (hasChild) {
+          for (var m2 in v) {
+            if (m2 === "#text") xml += v[m2];
+            else if (m2 === "#cdata") xml += "<![CDATA[" + v[m2] + "]]>";
+            else if (m2.charAt(0) !== "@") xml += toXml(v[m2], m2, ind + "\t");
+          }
+          xml +=
+            (xml.charAt(xml.length - 1) === "\n" ? ind : "") +
+            "</" +
+            name +
+            ">";
+        }
+      } else {
+        xml += ind + "<" + name + ">" + v.toString() + "</" + name + ">";
+      }
+      return xml;
+    },
+    xml = "";
+  for (var m3 in o) xml += toXml(o[m3], m3, "");
+  return tab ? xml.replace(/\t/g, tab) : xml.replace(/\t|\n/g, "");
+}
+
+interface Props {
+  id?: string;
+  label?: string;
+  responses: ApiItem["responses"];
+}
+
+export function createStatusCodes({ id, label, responses }: Props) {
+  return [
+    create("StatusCodes", {
+      id: id,
+      label: label,
+      responses: responses,
+    }),
+    "\n\n",
+  ];
+}

package/src/markdown/createTermsOfService.ts

@@ -0,0 +1,30 @@
+/* ============================================================================
+ * 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 } from "./utils";
+
+export function createTermsOfService(termsOfService: string | undefined) {
+  if (!termsOfService) return "";
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "Terms of Service",
+      }),
+      create("a", {
+        href: `${termsOfService}`,
+        children: `{'${termsOfService}'}`,
+      }),
+    ],
+  });
+}

package/src/markdown/createVendorExtensions.ts

@@ -0,0 +1,22 @@
+/* ============================================================================
+ * 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 function createVendorExtensions(extensions: any) {
+  if (!extensions || typeof extensions !== "object") {
+    return undefined;
+  }
+  const rows: Array<string> = [];
+  extensions.map((extension: any) => {
+    const extensionRow = () => {
+      return `${extension.key}: ${JSON.stringify(extension.value)}`;
+    };
+    return rows.push(extensionRow());
+  });
+  return `\n\n\`\`\`
+${rows.join("\n")}
+\`\`\`\n\n`;
+}

package/src/markdown/createVersionBadge.ts

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

package/src/markdown/index.ts

@@ -0,0 +1,144 @@
+/* ============================================================================
+ * 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 { createAuthentication } from "./createAuthentication";
+import { createAuthorization } from "./createAuthorization";
+import { createCallbacks } from "./createCallbacks";
+import { createContactInfo } from "./createContactInfo";
+import { createDeprecationNotice } from "./createDeprecationNotice";
+import { createDescription } from "./createDescription";
+import { createDownload } from "./createDownload";
+import { createHeading } from "./createHeading";
+import { createLicense } from "./createLicense";
+import { createLogo } from "./createLogo";
+import { createMethodEndpoint } from "./createMethodEndpoint";
+import { createParamsDetails } from "./createParamsDetails";
+import { createRequestBodyDetails } from "./createRequestBodyDetails";
+import { createRequestHeader } from "./createRequestHeader";
+import { createStatusCodes } from "./createStatusCodes";
+import { createTermsOfService } from "./createTermsOfService";
+import { createVendorExtensions } from "./createVendorExtensions";
+import { createVersionBadge } from "./createVersionBadge";
+import { create, greaterThan, lessThan, render } from "./utils";
+import {
+  ContactObject,
+  LicenseObject,
+  MediaTypeObject,
+  SecuritySchemeObject,
+} from "../openapi/types";
+import {
+  ApiPageMetadata,
+  InfoPageMetadata,
+  SchemaPageMetadata,
+  TagPageMetadata,
+} from "../types";
+
+interface RequestBodyProps {
+  title: string;
+  body: {
+    content?: {
+      [key: string]: MediaTypeObject;
+    };
+    description?: string;
+    required?: boolean;
+  };
+}
+
+export function createApiPageMD({
+  title,
+  api: {
+    deprecated,
+    "x-deprecated-description": deprecatedDescription,
+    description,
+    method,
+    path,
+    extensions,
+    parameters,
+    requestBody,
+    responses,
+    callbacks,
+  },
+  infoPath,
+  frontMatter,
+}: ApiPageMetadata) {
+  return render([
+    `import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";\n`,
+    `import ParamsDetails from "@theme/ParamsDetails";\n`,
+    `import RequestSchema from "@theme/RequestSchema";\n`,
+    `import StatusCodes from "@theme/StatusCodes";\n`,
+    `import OperationTabs from "@theme/OperationTabs";\n`,
+    `import TabItem from "@theme/TabItem";\n`,
+    `import Heading from "@theme/Heading";\n\n`,
+    createHeading(title),
+    createMethodEndpoint(method, path),
+    infoPath && createAuthorization(infoPath),
+    frontMatter.show_extensions
+      ? createVendorExtensions(extensions)
+      : undefined,
+    createDeprecationNotice({ deprecated, description: deprecatedDescription }),
+    createDescription(description),
+    requestBody || parameters ? createRequestHeader("Request") : undefined,
+    createParamsDetails({ parameters }),
+    createRequestBodyDetails({
+      title: "Body",
+      body: requestBody,
+    } as RequestBodyProps),
+    createStatusCodes({ responses }),
+    createCallbacks({ callbacks }),
+  ]);
+}
+
+export function createInfoPageMD({
+  info: {
+    title,
+    version,
+    description,
+    contact,
+    license,
+    termsOfService,
+    logo,
+    darkLogo,
+  },
+  securitySchemes,
+  downloadUrl,
+}: InfoPageMetadata) {
+  return render([
+    `import ApiLogo from "@theme/ApiLogo";\n`,
+    `import Heading from "@theme/Heading";\n`,
+    `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import TabItem from "@theme/TabItem";\n`,
+    `import Export from "@theme/ApiExplorer/Export";\n\n`,
+
+    createVersionBadge(version),
+    createDownload(downloadUrl),
+    createHeading(title),
+    createLogo(logo, darkLogo),
+    createDescription(description),
+    createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
+    createContactInfo(contact as ContactObject),
+    createTermsOfService(termsOfService),
+    createLicense(license as LicenseObject),
+  ]);
+}
+
+export function createTagPageMD({ tag: { description } }: TagPageMetadata) {
+  return render([createDescription(description)]);
+}
+
+export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
+  const { title = "", description } = schema;
+  return render([
+    `import Schema from "@theme/Schema";\n`,
+    `import Heading from "@theme/Heading";\n\n`,
+    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createDescription(description),
+    create("Schema", {
+      schema: schema,
+      schemaType: "response",
+    }),
+  ]);
+}

package/src/markdown/schema.test.ts

@@ -0,0 +1,208 @@
+/* ============================================================================
+ * 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:** `non-empty`";
+    const actual = getQualifierMessage({ minLength: 1 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render maxLength", () => {
+    const expected = "**Possible values:** `<= 40 characters`";
+    const actual = getQualifierMessage({ maxLength: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minLength and maxLength", () => {
+    const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
+    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:** `non-empty` and `<= 40 characters`, 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`";
+    const actual = getQualifierMessage({ minimum: 1 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render maximum", () => {
+    const expected = "**Possible values:** `<= 40`";
+    const actual = getQualifierMessage({ maximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render numeric exclusiveMinimum", () => {
+    const expected = "**Possible values:** `> 1`";
+    const actual = getQualifierMessage({ exclusiveMinimum: 1 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render numeric exclusiveMaximum", () => {
+    const expected = "**Possible values:** `< 40`";
+    const actual = getQualifierMessage({ exclusiveMaximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render boolean exclusiveMinimum", () => {
+    const expected = "**Possible values:** `> 1`";
+    const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: true });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render boolean exclusiveMaximum", () => {
+    const expected = "**Possible values:** `< 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`";
+    const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: false });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render maximum when exclusiveMaximum is false", () => {
+    const expected = "**Possible values:** `<= 40`";
+    const actual = getQualifierMessage({
+      maximum: 40,
+      exclusiveMaximum: false,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum and maximum", () => {
+    const expected = "**Possible values:** `>= 1` and `<= 40`";
+    const actual = getQualifierMessage({ minimum: 1, maximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render 0 minimum and maximum", () => {
+    const expected = "**Possible values:** `>= 0` and `<= 40`";
+    const actual = getQualifierMessage({ minimum: 0, maximum: 40 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum and 0 maximum", () => {
+    const expected = "**Possible values:** `>= -10` and `<= 0`";
+    const actual = getQualifierMessage({ minimum: -10, maximum: 0 });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render boolean exclusiveMinimum and maximum", () => {
+    const expected = "**Possible values:** `> 1` and `<= 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` and `< 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` and `<= 40`";
+    const actual = getQualifierMessage({
+      exclusiveMinimum: 1,
+      maximum: 40,
+    });
+    expect(actual).toBe(expected);
+  });
+
+  it("should render minimum and numeric exclusiveMaximum", () => {
+    const expected = "**Possible values:** `>= 1` and `< 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` and `< 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,185 @@
+/* ============================================================================
+ * 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.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;
+  }
+
+  if (schema.title && schema.type) {
+    return `${schema.title} (${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:
+  // - uniqueItems
+  // - maxProperties
+  // - minProperties
+  // - multipleOf
+  if (!schema) {
+    return undefined;
+  }
+
+  if (
+    schema.items &&
+    schema.minItems === undefined &&
+    schema.maxItems === undefined
+  ) {
+    return getQualifierMessage(schema.items);
+  }
+
+  let message = "**Possible values:** ";
+
+  let qualifierGroups = [];
+
+  if (schema.items && schema.items.enum) {
+    if (schema.items.enum) {
+      qualifierGroups.push(
+        `[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`
+      );
+    }
+  }
+
+  if (schema.minLength || schema.maxLength) {
+    let lengthQualifier = "";
+    let minLength;
+    let maxLength;
+    if (schema.minLength && schema.minLength > 1) {
+      minLength = `\`>= ${schema.minLength} characters\``;
+    }
+    if (schema.minLength && schema.minLength === 1) {
+      minLength = `\`non-empty\``;
+    }
+    if (schema.maxLength) {
+      maxLength = `\`<= ${schema.maxLength} characters\``;
+    }
+
+    if (minLength && !maxLength) {
+      lengthQualifier += minLength;
+    }
+    if (maxLength && !minLength) {
+      lengthQualifier += maxLength;
+    }
+    if (minLength && maxLength) {
+      lengthQualifier += `${minLength} and ${maxLength}`;
+    }
+
+    qualifierGroups.push(lengthQualifier);
+  }
+
+  if (
+    schema.minimum != null ||
+    schema.maximum != null ||
+    typeof schema.exclusiveMinimum === "number" ||
+    typeof schema.exclusiveMaximum === "number"
+  ) {
+    let minmaxQualifier = "";
+    let minimum;
+    let maximum;
+    if (typeof schema.exclusiveMinimum === "number") {
+      minimum = `\`> ${schema.exclusiveMinimum}\``;
+    } else if (schema.minimum != null && !schema.exclusiveMinimum) {
+      minimum = `\`>= ${schema.minimum}\``;
+    } else if (schema.minimum != null && schema.exclusiveMinimum === true) {
+      minimum = `\`> ${schema.minimum}\``;
+    }
+    if (typeof schema.exclusiveMaximum === "number") {
+      maximum = `\`< ${schema.exclusiveMaximum}\``;
+    } else if (schema.maximum != null && !schema.exclusiveMaximum) {
+      maximum = `\`<= ${schema.maximum}\``;
+    } else if (schema.maximum != null && schema.exclusiveMaximum === true) {
+      maximum = `\`< ${schema.maximum}\``;
+    }
+
+    if (minimum && !maximum) {
+      minmaxQualifier += minimum;
+    }
+    if (maximum && !minimum) {
+      minmaxQualifier += maximum;
+    }
+    if (minimum && maximum) {
+      minmaxQualifier += `${minimum} and ${maximum}`;
+    }
+
+    qualifierGroups.push(minmaxQualifier);
+  }
+
+  if (schema.pattern) {
+    qualifierGroups.push(
+      `Value must match regular expression \`${schema.pattern}\``
+    );
+  }
+
+  // Check if discriminator mapping
+  const discriminator = schema as any;
+  if (discriminator.mapping) {
+    const values = Object.keys(discriminator.mapping);
+    qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
+  if (schema.enum) {
+    qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
+  if (schema.minItems) {
+    qualifierGroups.push(`\`>= ${schema.minItems}\``);
+  }
+
+  if (schema.maxItems) {
+    qualifierGroups.push(`\`<= ${schema.maxItems}\``);
+  }
+
+  if (qualifierGroups.length === 0) {
+    return undefined;
+  }
+
+  return message + qualifierGroups.join(", ");
+}