docusaurus-theme-openapi-docs 1.0.0

package/lib-next/theme/Tabs/index.js

@@ -0,0 +1,258 @@
+/* ============================================================================
+ * 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, {
+  Children,
+  cloneElement,
+  isValidElement,
+  useRef,
+  useState,
+} from "react";
+
+import {
+  duplicates,
+  useScrollPositionBlocker,
+  useTabGroupChoice,
+} from "@docusaurus/theme-common";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import clsx from "clsx";
+
+import styles from "./styles.module.css"; // A very rough duck type, but good enough to guard against mistakes while
+
+// allowing customization
+
+function isTabItem(comp) {
+  return typeof comp.props.value !== "undefined";
+}
+
+function ResponseCodeTabs(props) {
+  const {
+    lazy,
+    block,
+    defaultValue: defaultValueProp,
+    values: valuesProp,
+    groupId,
+    className,
+  } = props;
+  const children = Children.map(props.children, (child) => {
+    if (isValidElement(child) && isTabItem(child)) {
+      return child;
+    } // child.type.name will give non-sensical values in prod because of
+    // minification, but we assume it won't throw in prod.
+
+    throw new Error(
+      `Docusaurus error: Bad <Tabs> child <${
+        // @ts-expect-error: guarding against unexpected cases
+        typeof child.type === "string" ? child.type : child.type.name
+      }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`
+    );
+  });
+  const values =
+    valuesProp ?? // We only pick keys that we recognize. MDX would inject some keys by default
+    children.map(({ props: { value, label, attributes } }) => ({
+      value,
+      label,
+      attributes,
+    }));
+  const dup = duplicates(values, (a, b) => a.value === b.value);
+
+  if (dup.length > 0) {
+    throw new Error(
+      `Docusaurus error: Duplicate values "${dup
+        .map((a) => a.value)
+        .join(", ")}" found in <Tabs>. Every value needs to be unique.`
+    );
+  } // When defaultValueProp is null, don't show a default tab
+
+  const defaultValue =
+    defaultValueProp === null
+      ? defaultValueProp
+      : defaultValueProp ??
+        children.find((child) => child.props.default)?.props.value ??
+        children[0]?.props.value;
+
+  if (defaultValue !== null && !values.some((a) => a.value === defaultValue)) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${values
+        .map((a) => a.value)
+        .join(
+          ", "
+        )}. If you intend to show no default tab, use defaultValue={null} instead.`
+    );
+  }
+
+  const { tabGroupChoices, setTabGroupChoices } = useTabGroupChoice();
+  const [selectedValue, setSelectedValue] = useState(defaultValue);
+  const tabRefs = [];
+  const { blockElementScrollPositionUntilNextRender } =
+    useScrollPositionBlocker();
+
+  if (groupId != null) {
+    const relevantTabGroupChoice = tabGroupChoices[groupId];
+
+    if (
+      relevantTabGroupChoice != null &&
+      relevantTabGroupChoice !== selectedValue &&
+      values.some((value) => value.value === relevantTabGroupChoice)
+    ) {
+      setSelectedValue(relevantTabGroupChoice);
+    }
+  }
+
+  const handleTabChange = (event) => {
+    const newTab = event.currentTarget;
+    const newTabIndex = tabRefs.indexOf(newTab);
+    const newTabValue = values[newTabIndex].value;
+
+    if (newTabValue !== selectedValue) {
+      blockElementScrollPositionUntilNextRender(newTab);
+      setSelectedValue(newTabValue);
+
+      if (groupId != null) {
+        setTabGroupChoices(groupId, newTabValue);
+      }
+    }
+  };
+
+  const handleKeydown = (event) => {
+    let focusElement = null;
+
+    switch (event.key) {
+      case "ArrowRight": {
+        const nextTab = tabRefs.indexOf(event.currentTarget) + 1;
+        focusElement = tabRefs[nextTab] || tabRefs[0];
+        break;
+      }
+
+      case "ArrowLeft": {
+        const prevTab = tabRefs.indexOf(event.currentTarget) - 1;
+        focusElement = tabRefs[prevTab] || tabRefs[tabRefs.length - 1];
+        break;
+      }
+
+      default:
+        break;
+    }
+
+    focusElement?.focus();
+  };
+
+  const tabItemListContainerRef = useRef(null);
+  const showTabArrows = values.length >= 5;
+
+  const handleRightClick = () => {
+    tabItemListContainerRef.current.scrollLeft += 90;
+  };
+
+  const handleLeftClick = () => {
+    tabItemListContainerRef.current.scrollLeft -= 90;
+  };
+
+  return (
+    <div className="tabs__container">
+      <div className={styles.responseTabsTopSection}>
+        <strong>Responses</strong>
+        <div className={styles.responseTabsContainer}>
+          {showTabArrows && (
+            <button
+              className={clsx(styles.tabArrow, styles.tabArrowLeft)}
+              onClick={handleLeftClick}
+            />
+          )}
+          <ul
+            ref={tabItemListContainerRef}
+            role="tablist"
+            aria-orientation="horizontal"
+            className={clsx(
+              styles.responseTabsListContainer,
+              "tabs",
+              {
+                "tabs--block": block,
+              },
+              className
+            )}
+          >
+            {values.map(({ value, label, attributes }) => {
+              const responseTabDotStyle =
+                parseInt(value) >= 400
+                  ? styles.responseTabDotDanger
+                  : parseInt(value) >= 200 && parseInt(value) < 300
+                  ? styles.responseTabDotSuccess
+                  : styles.responseTabDotInfo;
+
+              return (
+                <li
+                  role="tab"
+                  tabIndex={selectedValue === value ? 0 : -1}
+                  aria-selected={selectedValue === value}
+                  key={value}
+                  ref={(tabControl) => tabRefs.push(tabControl)}
+                  onKeyDown={handleKeydown}
+                  onFocus={handleTabChange}
+                  onClick={handleTabChange}
+                  {...attributes}
+                  className={clsx(
+                    "tabs__item",
+                    styles.tabItem,
+                    attributes?.className,
+                    {
+                      [styles.responseTabActive]: selectedValue === value,
+                    }
+                  )}
+                >
+                  <div
+                    className={clsx(styles.responseTabDot, responseTabDotStyle)}
+                  />
+                  {label ?? value}
+                </li>
+              );
+            })}
+          </ul>
+          {showTabArrows && (
+            <button
+              className={clsx(styles.tabArrow, styles.tabArrowRight)}
+              onClick={handleRightClick}
+            />
+          )}
+        </div>
+      </div>
+      <hr />
+      {lazy ? (
+        cloneElement(
+          children.filter(
+            (tabItem) => tabItem.props.value === selectedValue
+          )[0],
+          {
+            className: clsx("margin-vert--md", styles.responseSchemaContainer),
+          }
+        )
+      ) : (
+        <div
+          className={clsx("margin-vert--md", styles.responseSchemaContainer)}
+        >
+          {children.map((tabItem, i) =>
+            cloneElement(tabItem, {
+              key: i,
+              hidden: tabItem.props.value !== selectedValue,
+            })
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function Tabs(props) {
+  const isBrowser = useIsBrowser();
+  return (
+    <ResponseCodeTabs // Remount tabs after hydration
+      // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
+      key={String(isBrowser)}
+      {...props}
+    />
+  );
+}

package/lib-next/theme/Tabs/styles.module.css

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.tabItem {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 2.5rem;
+  margin-top: 0 !important;
+  margin-right: 0.5rem;
+  border: 1px solid var(--openapi-code-dim-dark);
+  border-radius: var(--ifm-global-radius);
+  font-weight: var(--ifm-font-weight-normal);
+  color: var(--openapi-code-dim-dark);
+}
+
+.tabItem:hover {
+  color: var(--ifm-color-emphasis-500) !important;
+}
+
+.tabItem:last-child {
+  margin-right: 0 !important;
+}
+
+/* Open API Response Code Tabs */
+.responseTabsTopSection {
+  margin-top: 2rem;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.responseTabsContainer {
+  display: flex;
+  align-items: center;
+  max-width: 390px;
+  padding-left: 1rem;
+  overflow: hidden;
+}
+
+.responseTabsListContainer {
+  padding: 0 0.25rem;
+  overflow-y: hidden;
+  overflow-x: scroll;
+  scroll-behavior: smooth;
+}
+
+.responseTabsListContainer::-webkit-scrollbar {
+  display: none;
+}
+
+/* Response Code Tabs - Colored Dots */
+.responseTabDot {
+  width: 12.5px;
+  height: 12.5px;
+  margin-right: 5px;
+  border-radius: 50%;
+}
+
+.responseTabDotSuccess {
+  background-color: var(--ifm-color-success);
+}
+
+.responseTabDotDanger {
+  background-color: var(--ifm-color-danger);
+}
+
+.responseTabDotInfo {
+  background-color: var(--ifm-color-info);
+}
+
+.responseTabActive {
+  border: 1px solid var(--ifm-color-primary);
+  color: var(--ifm-color-primary);
+}
+
+.responseSchemaContainer {
+  max-width: 600px;
+}
+
+/* Tab Arrows */
+.tabArrow {
+  content: "";
+  height: 1.25rem;
+  width: 1.25rem;
+  padding: 0 0.75rem;
+  border: none;
+  min-width: 1.25rem;
+  background: var(--ifm-menu-link-sublist-icon) 50% / 2rem 2rem;
+  filter: var(--ifm-menu-link-sublist-icon-filter);
+}
+
+.tabArrow:hover {
+  cursor: pointer;
+}
+.tabArrowLeft {
+  transform: rotate(270deg);
+}
+.tabArrowRight {
+  transform: rotate(90deg);
+}
+
+@media screen and (max-width: 500px) {
+  .responseTabsTopSection {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .responseTabsContainer {
+    width: 100%;
+    margin-top: var(--ifm-spacing-vertical);
+    padding: 0;
+  }
+}

package/lib-next/theme-classic.d.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.
+ * ========================================================================== */
+
+/// <reference types="@docusaurus/theme-classic" />

package/lib-next/theme-openapi.d.ts

@@ -0,0 +1,48 @@
+/* ============================================================================
+ * 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-plugin-openapi-docs" />
+
+declare module "@docusaurus/plugin-content-docs-types" {
+  // Makes all properties visible when hovering over the type
+  type Expand<T extends Record<string, unknown>> = { [P in keyof T]: T[P] };
+
+  export type SidebarItemBase = {
+    className?: string;
+    customProps?: Record<string, unknown>;
+  };
+
+  export type SidebarItemLink = SidebarItemBase & {
+    type: "link";
+    href: string;
+    label: string;
+    docId: string;
+  };
+
+  type SidebarItemCategoryBase = SidebarItemBase & {
+    type: "category";
+    label: string;
+    collapsed: boolean;
+    collapsible: boolean;
+  };
+
+  export type PropSidebarItemCategory = Expand<
+    SidebarItemCategoryBase & {
+      items: PropSidebarItem[];
+    }
+  >;
+
+  export type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
+  export type PropSidebar = PropSidebarItem[];
+  export type PropSidebars = {
+    [sidebarId: string]: PropSidebar;
+  };
+}
+
+declare module "docusaurus-theme-openapi-docs" {
+  export type ThemeConfig = Partial<import("./types").ThemeConfig>;
+}

package/lib-next/theme-translations.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 "@docusaurus/theme-translations";

package/lib-next/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "docusaurus-theme-openapi-docs",
+  "description": "OpenAPI theme for Docusaurus.",
+  "version": "1.0.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi.git",
+    "directory": "packages/docusaurus-theme-openapi-docs"
+  },
+  "bugs": {
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi/issues"
+  },
+  "types": "src/theme-openapi.d.ts",
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "tsc --noEmit && yarn babel:lib && yarn babel:lib-next && yarn format:lib-next",
+    "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\"",
+    "babel:lib": "cross-env BABEL_ENV=lib babel src -d lib --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
+    "babel:lib-next": "cross-env BABEL_ENV=lib-next babel src -d lib-next --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
+    "format:lib-next": "prettier --config ../../.prettierrc.json --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^2.0.0-beta.18",
+    "@docusaurus/types": "^2.0.0-beta.18",
+    "@types/concurrently": "^6.3.0",
+    "@types/crypto-js": "^4.1.0",
+    "@types/fs-extra": "^9.0.13",
+    "@types/lodash": "^4.14.176",
+    "@types/mdx-js__react": "^1.5.4",
+    "@types/postman-collection": "^3.5.7",
+    "@types/rtlcss": "^3.1.1",
+    "concurrently": "^5.2.0"
+  },
+  "dependencies": {
+    "@docusaurus/theme-common": "^2.0.0-beta.18",
+    "@mdx-js/react": "^1.6.21",
+    "@monaco-editor/react": "^4.3.1",
+    "@paloaltonetworks/postman-code-generators": "1.1.5-hotfix.5",
+    "@paloaltonetworks/postman-collection": "^4.1.0",
+    "@reduxjs/toolkit": "^1.7.1",
+    "buffer": "^6.0.3",
+    "clsx": "^1.1.1",
+    "crypto-js": "^4.1.1",
+    "docusaurus-plugin-openapi-docs": "1.0.0",
+    "immer": "^9.0.7",
+    "lodash": "^4.17.20",
+    "monaco-editor": "^0.31.1",
+    "prism-react-renderer": "^1.2.1",
+    "process": "^0.11.10",
+    "react-magic-dropzone": "^1.0.1",
+    "react-markdown": "^8.0.1",
+    "react-redux": "^7.2.0",
+    "redux-devtools-extension": "^2.13.8",
+    "webpack": "^5.61.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0",
+    "react-dom": "^16.8.4 || ^17.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "gitHead": "8905a438e86fc0a5cb9f033fb1b29630ff059af8"
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/* ============================================================================
+ * 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";
+
+import type { Plugin } from "@docusaurus/types";
+import { ProvidePlugin } from "webpack";
+
+export default function docusaurusThemeOpenAPI(): Plugin<void> {
+  return {
+    name: "docusaurus-theme-openapi",
+
+    getThemePath() {
+      return path.join(__dirname, "..", "lib-next", "theme");
+    },
+
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, "..", "src", "theme");
+    },
+
+    configureWebpack() {
+      return {
+        plugins: [
+          new ProvidePlugin({
+            Buffer: [require.resolve("buffer/"), "Buffer"],
+            process: require.resolve("process/browser"),
+          }),
+        ],
+        resolve: {
+          fallback: {
+            buffer: require.resolve("buffer/"),
+            process: require.resolve("process/browser"),
+          },
+        },
+      };
+    },
+  };
+}

package/src/markdown/createDescription.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.
+ * ========================================================================== */
+
+export function createDescription(description: string | undefined) {
+  if (!description) {
+    return "";
+  }
+  return `\n\n${description}\n\n`;
+}

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 "../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(", ");
+}