docusaurus-theme-openapi-docs 0.0.0-1000

package/src/markdown/schema.ts

@@ -0,0 +1,181 @@
+/* ============================================================================
+ * 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";
+
+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;
+  }
+
+  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(", ");
+}

package/src/markdown/utils.test.ts

@@ -0,0 +1,49 @@
+/* ============================================================================
+ * 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 { guard } from "./utils";
+
+describe("guard", () => {
+  it("should guard empty strings", () => {
+    const actual = guard("", (_) => {
+      throw new Error("Should not be called");
+    });
+    expect(actual).toBe("");
+  });
+
+  it("should guard undefined", () => {
+    const actual = guard(undefined, (value) => {
+      throw new Error("Should not be called");
+    });
+    expect(actual).toBe("");
+  });
+
+  it("should guard false booleans", () => {
+    const actual = guard(false, (value) => `${value}`);
+    expect(actual).toBe("");
+  });
+
+  it("should not guard strings", () => {
+    const actual = guard("hello", (value) => value);
+    expect(actual).toBe("hello");
+  });
+
+  it("should not guard numbers", () => {
+    const actual = guard(1, (value) => `${value}`);
+    expect(actual).toBe("1");
+  });
+
+  it("should not guard numbers equals to 0", () => {
+    const actual = guard(0, (value) => `${value}`);
+    expect(actual).toBe("0");
+  });
+
+  it("should not guard true booleans", () => {
+    const actual = guard(true, (value) => `${value}`);
+    expect(actual).toBe("true");
+  });
+});

package/src/markdown/utils.ts

@@ -0,0 +1,59 @@
+/* ============================================================================
+ * 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 { ReactNode } from "react";
+
+/** @deprecated use ReactNode from React instead */
+export type Children = ReactNode;
+
+export type Props = Record<string, any> & { children?: ReactNode };
+
+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 | string,
+  cb: (value: T) => ReactNode
+) {
+  if (!!value || value === 0) {
+    const children = cb(value as T);
+    return render(children);
+  }
+  return "";
+}
+
+export function render(children: ReactNode) {
+  if (Array.isArray(children)) {
+    return children.filter((c) => c !== undefined).join("");
+  }
+  return children ?? "";
+}
+
+export function toString(value: any): string | undefined {
+  // Return as-is if already string
+  if (typeof value === "string") {
+    return value;
+  }
+  // Return undefined if null or undefined
+  if (value == null) {
+    return undefined;
+  }
+  // Return formatted array if Array
+  if (Array.isArray(value)) {
+    return `[${value.join(", ")}]`;
+  }
+  // Coerce to string in all other cases,
+  return value + "";
+}

package/src/plugin-content-docs.d.ts

@@ -0,0 +1,20 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+/// <reference types="@docusaurus/theme-classic" />
+
+declare module "@docusaurus/plugin-content-docs/client" {
+  export function DocProvider({
+    children,
+    content,
+  }: {
+    children: ReactNode;
+    content: PropDocContent;
+  });
+
+  export function useDoc();
+}

package/src/postman-code-generators.d.ts

@@ -0,0 +1,9 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// TODO: Remove this when https://github.com/facebook/docusaurus/issues/6087 is resolved.
+declare module "postman-code-generators";

package/src/react-magic-dropzone.d.ts

@@ -0,0 +1,9 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// TODO: Remove this when https://github.com/facebook/docusaurus/issues/6087 is resolved.
+declare module "react-magic-dropzone";

package/src/theme/ApiExplorer/Accept/index.tsx

@@ -0,0 +1,36 @@
+/* ============================================================================
+ * 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 React from "react";
+
+import FormItem from "@theme/ApiExplorer/FormItem";
+import FormSelect from "@theme/ApiExplorer/FormSelect";
+import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+
+import { setAccept } from "./slice";
+
+function Accept() {
+  const value = useTypedSelector((state: any) => state.accept.value);
+  const options = useTypedSelector((state: any) => state.accept.options);
+  const dispatch = useTypedDispatch();
+
+  if (options.length <= 1) {
+    return null;
+  }
+
+  return (
+    <FormItem label="Accept">
+      <FormSelect
+        value={value}
+        options={options}
+        onChange={(e: any) => dispatch(setAccept(e.target.value))}
+      />
+    </FormItem>
+  );
+}
+
+export default Accept;

package/src/theme/ApiExplorer/Accept/slice.ts

@@ -0,0 +1,29 @@
+/* ============================================================================
+ * 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 { createSlice, PayloadAction } from "@reduxjs/toolkit";
+
+export interface State {
+  value: string;
+  options: string[];
+}
+
+const initialState: State = {} as any;
+
+export const slice = createSlice({
+  name: "accept",
+  initialState,
+  reducers: {
+    setAccept: (state, action: PayloadAction<string>) => {
+      state.value = action.payload;
+    },
+  },
+});
+
+export const { setAccept } = slice.actions;
+
+export default slice.reducer;

package/src/theme/ApiExplorer/ApiCodeBlock/Container/_Container.scss

@@ -0,0 +1,7 @@
+.openapi-explorer__code-block-container {
+  height: 100%;
+  background: var(--prism-background-color);
+  color: var(--prism-color);
+  margin-bottom: unset;
+  box-shadow: var(--ifm-global-shadow-lw);
+}

package/src/theme/ApiExplorer/ApiCodeBlock/Container/index.tsx

@@ -0,0 +1,32 @@
+/* ============================================================================
+ * 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 React, { ComponentProps } from "react";
+
+import { ThemeClassNames, usePrismTheme } from "@docusaurus/theme-common";
+import { getPrismCssVariables } from "@docusaurus/theme-common/internal";
+import clsx from "clsx";
+
+export default function CodeBlockContainer<T extends "div" | "pre">({
+  as: As,
+  ...props
+}: { as: T } & ComponentProps<T>): React.JSX.Element {
+  const prismTheme = usePrismTheme();
+  const prismCssVariables = getPrismCssVariables(prismTheme);
+  return (
+    <As
+      // Polymorphic components are hard to type, without `oneOf` generics
+      {...(props as any)}
+      style={prismCssVariables}
+      className={clsx(
+        "openapi-explorer__code-block-container",
+        props.className,
+        ThemeClassNames.common.codeBlock
+      )}
+    />
+  );
+}

package/src/theme/ApiExplorer/ApiCodeBlock/Content/Element.tsx

@@ -0,0 +1,34 @@
+/* ============================================================================
+ * 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 React from "react";
+
+import Container from "@theme/ApiExplorer/ApiCodeBlock/Container";
+import type { Props } from "@theme/CodeBlock/Content/Element";
+import clsx from "clsx";
+
+// <pre> tags in markdown map to CodeBlocks. They may contain JSX children. When
+// the children is not a simple string, we just return a styled block without
+// actually highlighting.
+export default function CodeBlockJSX({
+  children,
+  className,
+}: Props): React.JSX.Element {
+  return (
+    <Container
+      as="pre"
+      tabIndex={0}
+      className={clsx(
+        "openapi-explorer__code-block-standalone",
+        "thin-scrollbar",
+        className
+      )}
+    >
+      <code className="openapi-explorer__code-block-lines">{children}</code>
+    </Container>
+  );
+}

package/src/theme/ApiExplorer/ApiCodeBlock/Content/String.tsx

@@ -0,0 +1,134 @@
+/* ============================================================================
+ * 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 React from "react";
+
+import { useThemeConfig, usePrismTheme } from "@docusaurus/theme-common";
+import {
+  parseCodeBlockTitle,
+  parseLanguage,
+  parseLines,
+  containsLineNumbers,
+  useCodeWordWrap,
+} from "@docusaurus/theme-common/internal";
+import Container from "@theme/ApiExplorer/ApiCodeBlock/Container";
+import CopyButton from "@theme/ApiExplorer/ApiCodeBlock/CopyButton";
+import ExpandButton from "@theme/ApiExplorer/ApiCodeBlock/ExpandButton";
+import Line from "@theme/ApiExplorer/ApiCodeBlock/Line";
+import WordWrapButton from "@theme/ApiExplorer/ApiCodeBlock/WordWrapButton";
+import type { Props } from "@theme/CodeBlock/Content/String";
+import clsx from "clsx";
+import { Highlight, Language } from "prism-react-renderer";
+
+export default function CodeBlockString({
+  children,
+  className: blockClassName = "",
+  metastring,
+  title: titleProp,
+  showLineNumbers: showLineNumbersProp,
+  language: languageProp,
+}: Props): React.JSX.Element {
+  const {
+    prism: { defaultLanguage, magicComments },
+  } = useThemeConfig();
+  const language =
+    languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage;
+  const prismTheme = usePrismTheme();
+  const wordWrap = useCodeWordWrap();
+  // We still parse the metastring in case we want to support more syntax in the
+  // future. Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
+  const title = parseCodeBlockTitle(metastring) || titleProp;
+  const { lineClassNames, code } = parseLines(children, {
+    metastring,
+    language,
+    magicComments,
+  });
+  const showLineNumbers =
+    showLineNumbersProp ?? containsLineNumbers(metastring);
+
+  return (
+    <Container
+      as="div"
+      className={clsx(
+        blockClassName,
+        language &&
+          !blockClassName.includes(`language-${language}`) &&
+          `language-${language}`
+      )}
+    >
+      {title && (
+        <div className="openapi-explorer__code-block-title">{title}</div>
+      )}
+      <div className="openapi-explorer__code-block-content">
+        <Highlight
+          // {...defaultProps}
+          theme={prismTheme}
+          code={code}
+          language={language ?? "text"}
+        >
+          {({ className, tokens, getLineProps, getTokenProps }) => (
+            <pre
+              /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
+              tabIndex={0}
+              ref={wordWrap.codeBlockRef}
+              className={clsx(
+                className,
+                "openapi-explorer__code-block",
+                "thin-scrollbar"
+              )}
+            >
+              <code
+                className={clsx(
+                  "openapi-explorer__code-block-lines",
+                  showLineNumbers &&
+                    "openapi-explorer__code-block-lines-numbering"
+                )}
+              >
+                {tokens.map((line, i) => (
+                  <Line
+                    key={i}
+                    line={line}
+                    getLineProps={getLineProps}
+                    getTokenProps={getTokenProps}
+                    classNames={lineClassNames[i]}
+                    showLineNumbers={showLineNumbers}
+                  />
+                ))}
+              </code>
+            </pre>
+          )}
+        </Highlight>
+        <div className="openapi-explorer__code-block-btn-group">
+          {(wordWrap.isEnabled || wordWrap.isCodeScrollable) && (
+            <WordWrapButton
+              className="openapi-explorer__code-block-code-btn"
+              onClick={() => wordWrap.toggle()}
+              isEnabled={wordWrap.isEnabled}
+            />
+          )}
+          <CopyButton
+            className="openapi-explorer__code-block-code-btn"
+            code={code}
+          />
+          <ExpandButton
+            className={clsx(
+              "openapi-explorer__code-block-code-btn",
+              "openapi-explorer__expand-btn"
+            )}
+            code={code}
+            language={(language ?? "text") as Language}
+            showLineNumbers={showLineNumbers}
+            blockClassName={blockClassName}
+            title={title}
+            lineClassNames={lineClassNames}
+          />
+        </div>
+      </div>
+    </Container>
+  );
+}