docusaurus-theme-openapi-docs 0.0.0-1000

package/src/theme/SchemaItem/_SchemaItem.scss

@@ -0,0 +1,89 @@
+.openapi-schema__container {
+  &:hover {
+    .openapi-schema__property {
+      color: var(--ifm-color-primary);
+    }
+  }
+}
+
+.openapi-schema__list-item {
+  list-style: none;
+  position: relative;
+  margin: 0 !important;
+  padding: 5px 0 5px 1rem;
+  border-left: thin solid var(--openapi-tree-line-color) !important;
+
+  // Horizontal line styling for schema properties
+  &::before {
+    position: absolute;
+    top: 10px;
+    left: 0;
+    width: 0.7rem;
+    /* width of horizontal line */
+    height: 0.5rem;
+    /* vertical position of line */
+    vertical-align: top;
+    border-bottom: thin solid var(--openapi-tree-line-color);
+    content: "";
+    display: inline-block;
+  }
+}
+
+.openapi-schema__name {
+  opacity: 0.6;
+  padding-left: 0.3rem;
+}
+
+.openapi-schema__required {
+  display: inline-flex;
+  align-items: center;
+  font-size: 10.5px;
+  font-weight: bold;
+  text-transform: uppercase;
+  color: var(--openapi-required);
+  margin-left: 1%;
+  background-color: transparent;
+}
+
+.openapi-schema__deprecated {
+  display: flex;
+  align-items: center;
+  font-size: 10.5px;
+  font-weight: bold;
+  text-transform: uppercase;
+  color: var(--openapi-deprecated);
+  margin-left: 1%;
+  background-color: transparent;
+}
+
+.openapi-schema__nullable {
+  display: flex;
+  align-items: center;
+  font-size: 10.5px;
+  font-weight: bold;
+  text-transform: uppercase;
+  color: var(--openapi-nullable);
+  margin-left: 1%;
+  background-color: transparent;
+}
+
+.openapi-schema__strikethrough {
+  text-decoration: line-through;
+}
+
+.openapi-schema__property {
+  margin-top: 1.25px;
+  font-family: var(--ifm-font-family-monospace);
+  transition: 300ms;
+}
+
+.openapi-schema__divider {
+  flex-grow: 1;
+  border-bottom: thin solid var(--ifm-toc-border-color);
+  margin: 10px;
+}
+
+.openapi-schema__container {
+  display: flex;
+  align-items: center;
+}

package/src/theme/SchemaItem/index.tsx

@@ -0,0 +1,198 @@
+/* ============================================================================
+ * 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, { ReactNode } from "react";
+
+import Markdown from "@theme/Markdown";
+import clsx from "clsx";
+
+import { guard } from "../../markdown/utils";
+
+export interface Props {
+  children?: ReactNode;
+  collapsible?: boolean;
+  name?: string;
+  qualifierMessage?: string | undefined;
+  required?: boolean;
+  schemaName?: string;
+  // TODO should probably be typed
+  schema?: any;
+  discriminator?: boolean;
+}
+
+const transformEnumDescriptions = (
+  enumDescriptions?: Record<string, string>
+) => {
+  if (enumDescriptions) {
+    return Object.entries(enumDescriptions);
+  }
+
+  return [];
+};
+
+const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
+  if (enumDescriptions?.length) {
+    return `| Enum Value | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+
+  return "";
+};
+
+export default function SchemaItem(props: Props) {
+  const {
+    children: collapsibleSchemaContent,
+    collapsible,
+    name,
+    qualifierMessage,
+    required,
+    schemaName,
+    schema,
+  } = props;
+  let deprecated;
+  let schemaDescription;
+  let defaultValue: string | undefined;
+  let example: string | undefined;
+  let nullable;
+  let enumDescriptions: [string, string][] = [];
+
+  if (schema) {
+    deprecated = schema.deprecated;
+    schemaDescription = schema.description;
+    enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
+    defaultValue = schema.default;
+    example = schema.example;
+    nullable =
+      schema.nullable ||
+      (Array.isArray(schema.type) && schema.type.includes("null")); // support JSON Schema nullable
+  }
+
+  const renderRequired = guard(
+    Array.isArray(required) ? required.includes(name) : required,
+    () => <span className="openapi-schema__required">required</span>
+  );
+
+  const renderDeprecated = guard(deprecated, () => (
+    <span className="openapi-schema__deprecated">deprecated</span>
+  ));
+
+  const renderNullable = guard(nullable, () => (
+    <span className="openapi-schema__nullable">nullable</span>
+  ));
+
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <div style={{ marginTop: ".5rem" }}>
+          <Markdown>{value}</Markdown>
+        </div>
+      );
+    }
+  );
+
+  const renderSchemaDescription = guard(schemaDescription, (description) => (
+    <>
+      <Markdown>{description}</Markdown>
+    </>
+  ));
+
+  const renderQualifierMessage = guard(qualifierMessage, (message) => (
+    <>
+      <Markdown>{message}</Markdown>
+    </>
+  ));
+
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return (
+          <div>
+            <strong>Default value: </strong>
+            <span>
+              <code>{defaultValue}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Default value: </strong>
+          <span>
+            <code>{JSON.stringify(defaultValue)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
+  function renderExample() {
+    if (example !== undefined) {
+      if (typeof example === "string") {
+        return (
+          <div>
+            <strong>Example: </strong>
+            <span>
+              <code>{example}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Example: </strong>
+          <span>
+            <code>{JSON.stringify(example)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
+  const schemaContent = (
+    <div>
+      <span className="openapi-schema__container">
+        <strong
+          className={clsx("openapi-schema__property", {
+            "openapi-schema__strikethrough": deprecated,
+          })}
+        >
+          {name}
+        </strong>
+        <span className="openapi-schema__name">
+          {Array.isArray(schemaName) ? schemaName.join(" | ") : schemaName}
+        </span>
+        {(nullable || required || deprecated) && (
+          <span className="openapi-schema__divider"></span>
+        )}
+        {renderNullable}
+        {renderRequired}
+        {renderDeprecated}
+      </span>
+      {renderSchemaDescription}
+      {renderEnumDescriptions}
+      {renderQualifierMessage}
+      {renderDefaultValue()}
+      {renderExample()}
+      {collapsibleSchemaContent ?? collapsibleSchemaContent}
+    </div>
+  );
+
+  return (
+    <div className="openapi-schema__list-item">
+      {collapsible ? collapsibleSchemaContent : schemaContent}
+    </div>
+  );
+}

package/src/theme/SchemaTabs/_SchemaTabs.scss

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+
+.openapi-tabs__schema-item {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.35rem 0.7rem;
+  border: 1px solid transparent;
+  margin-top: 0 !important;
+  margin-right: 0.5rem;
+  font-weight: var(--ifm-font-weight-bold);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 10px;
+  white-space: nowrap;
+  transition: 300ms;
+
+  &:hover {
+    background-color: transparent;
+    border: 1px solid var(--ifm-toc-border-color);
+  }
+
+  &.active {
+    border: 1px solid var(--ifm-color-primary);
+    color: var(--ifm-color-primary);
+  }
+
+  &:last-child {
+    margin-right: 0 !important;
+  }
+}
+
+.openapi-tabs__schema-list-container {
+  overflow-y: hidden;
+  overflow-x: scroll;
+  scroll-behavior: smooth;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+
+  &.active {
+    background-color: var(--ifm-color-emphasis-100);
+  }
+}
+
+.openapi-tabs__schema-label {
+  white-space: nowrap;
+}
+
+.openapi-tabs__schema-tabs-container {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  overflow: hidden;
+}

package/src/theme/SchemaTabs/index.tsx

@@ -0,0 +1,224 @@
+/* ============================================================================
+ * 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, {
+  cloneElement,
+  useRef,
+  useEffect,
+  useState,
+  ReactElement,
+  LegacyRef,
+} from "react";
+
+import {
+  sanitizeTabsChildren,
+  TabProps,
+  useScrollPositionBlocker,
+  useTabs,
+} from "@docusaurus/theme-common/internal";
+import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import clsx from "clsx";
+import flatten from "lodash/flatten";
+
+function TabList({
+  className,
+  block,
+  selectedValue,
+  selectValue,
+  tabValues,
+}: TabProps & ReturnType<typeof useTabs>) {
+  const tabRefs: (HTMLLIElement | null)[] = [];
+  const { blockElementScrollPositionUntilNextRender } =
+    useScrollPositionBlocker();
+
+  const handleTabChange = (
+    event:
+      | React.FocusEvent<HTMLLIElement>
+      | React.MouseEvent<HTMLLIElement>
+      | React.KeyboardEvent<HTMLLIElement>
+  ) => {
+    const newTab = event.currentTarget;
+    const newTabIndex = tabRefs.indexOf(newTab);
+    const newTabValue = tabValues[newTabIndex].value;
+
+    if (newTabValue !== selectedValue) {
+      blockElementScrollPositionUntilNextRender(newTab);
+      selectValue(newTabValue);
+    }
+  };
+
+  const handleKeydown = (event: React.KeyboardEvent<HTMLLIElement>) => {
+    let focusElement: HTMLLIElement | null = null;
+
+    switch (event.key) {
+      case "Enter": {
+        handleTabChange(event);
+        break;
+      }
+      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<HTMLUListElement>(null);
+  const [showTabArrows, setShowTabArrows] = useState<boolean>(false);
+
+  useEffect(() => {
+    const resizeObserver = new ResizeObserver((entries) => {
+      for (let entry of entries) {
+        requestAnimationFrame(() => {
+          if (entry.target.clientWidth < entry.target.scrollWidth) {
+            setShowTabArrows(true);
+          } else {
+            setShowTabArrows(false);
+          }
+        });
+      }
+    });
+
+    resizeObserver.observe(tabItemListContainerRef.current!);
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, []);
+
+  const handleRightClick = (e: any) => {
+    e.preventDefault();
+    if (tabItemListContainerRef.current) {
+      tabItemListContainerRef.current.scrollLeft += 90;
+    }
+  };
+
+  const handleLeftClick = (e: any) => {
+    e.preventDefault();
+    if (tabItemListContainerRef.current) {
+      tabItemListContainerRef.current.scrollLeft -= 90;
+    }
+  };
+
+  return (
+    <div className="openapi-tabs__schema-tabs-container">
+      {showTabArrows && (
+        <button
+          className="openapi-tabs__arrow left"
+          onClick={handleLeftClick}
+        />
+      )}
+      <ul
+        ref={tabItemListContainerRef as LegacyRef<HTMLUListElement>}
+        role="tablist"
+        aria-orientation="horizontal"
+        className={clsx(
+          "openapi-tabs__schema-list-container",
+          "tabs",
+          {
+            "tabs--block": block,
+          },
+          className
+        )}
+      >
+        {tabValues.map(({ value, label, attributes }) => (
+          <li
+            // TODO extract TabListItem
+            role="tab"
+            tabIndex={selectedValue === value ? 0 : -1}
+            aria-selected={selectedValue === value}
+            key={value}
+            ref={(tabControl) => {
+              tabRefs.push(tabControl);
+            }}
+            onKeyDown={handleKeydown}
+            onClick={handleTabChange}
+            {...attributes}
+            className={clsx(
+              "tabs__item",
+              "openapi-tabs__schema-item",
+              attributes?.className as string,
+              {
+                active: selectedValue === value,
+              }
+            )}
+          >
+            <span className="openapi-tabs__schema-label">{label ?? value}</span>
+          </li>
+        ))}
+      </ul>
+      {showTabArrows && (
+        <button
+          className="openapi-tabs__arrow right"
+          onClick={handleRightClick}
+        />
+      )}
+    </div>
+  );
+}
+function TabContent({
+  lazy,
+  children,
+  selectedValue,
+}: TabProps & ReturnType<typeof useTabs>) {
+  const childTabs = (Array.isArray(children) ? children : [children]).filter(
+    Boolean
+  ) as ReactElement<TabItemProps>[];
+  const flattenedChildTabs = flatten(childTabs);
+  if (lazy) {
+    const selectedTabItem = flattenedChildTabs.find(
+      (tabItem) => tabItem.props.value === selectedValue
+    );
+    if (!selectedTabItem) {
+      // fail-safe or fail-fast? not sure what's best here
+      return null;
+    }
+    return cloneElement(selectedTabItem, { className: "margin-top--md" });
+  }
+  return (
+    <div className="margin-top--md">
+      {childTabs.map((tabItem, i) =>
+        cloneElement(tabItem, {
+          key: i,
+          hidden: tabItem.props.value !== selectedValue,
+        })
+      )}
+    </div>
+  );
+}
+function TabsComponent(props: TabProps): React.JSX.Element {
+  const tabs = useTabs(props);
+  return (
+    <div className="openapi-tabs__schema-container">
+      <TabList {...props} {...tabs} />
+      <TabContent {...props} {...tabs} />
+    </div>
+  );
+}
+export default function SchemaTabs(props: TabProps): React.JSX.Element {
+  const isBrowser = useIsBrowser();
+  return (
+    <TabsComponent
+      // Remount tabs after hydration
+      // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
+      key={String(isBrowser)}
+      {...props}
+    >
+      {sanitizeTabsChildren(props.children)}
+    </TabsComponent>
+  );
+}

package/src/theme/SkeletonLoader/index.tsx

@@ -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 React from "react";
+
+interface Props {
+  size?: "sm" | "md" | "lg";
+}
+
+const SkeletonLoader: React.FC<Props> = (props) => {
+  return <div className={`openapi-skeleton ${props.size ?? "md"}`}></div>;
+};
+
+export default SkeletonLoader;

package/src/theme/StatusCodes/index.tsx

@@ -0,0 +1,72 @@
+/* ============================================================================
+ * 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 ApiTabs from "@theme/ApiTabs";
+import Details from "@theme/Details";
+import Markdown from "@theme/Markdown";
+import ResponseHeaders from "@theme/ResponseHeaders";
+import ResponseSchema from "@theme/ResponseSchema";
+import TabItem from "@theme/TabItem";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/lib/types";
+
+interface Props {
+  id?: string;
+  label?: string;
+  responses: ApiItem["responses"];
+}
+
+const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
+  if (!responses) return null;
+
+  const codes = Object.keys(responses);
+  if (codes.length === 0) return null;
+
+  return (
+    <ApiTabs label={label} id={id}>
+      {codes.map((code) => {
+        const response = responses[code];
+        const responseHeaders = response.headers;
+
+        return (
+          // @ts-ignore
+          <TabItem key={code} label={code} value={code}>
+            <div>
+              {response.description && (
+                <div style={{ marginTop: ".5rem", marginBottom: ".5rem" }}>
+                  <Markdown>{response.description}</Markdown>
+                </div>
+              )}
+            </div>
+            {responseHeaders && (
+              <Details
+                className="openapi-markdown__details"
+                data-collapsed={true}
+                open={false}
+                style={{ textAlign: "left", marginBottom: "1rem" }}
+                summary={
+                  <summary>
+                    <strong>Response Headers</strong>
+                  </summary>
+                }
+              >
+                <ResponseHeaders responseHeaders={responseHeaders} />
+              </Details>
+            )}
+            <ResponseSchema
+              title="Schema"
+              body={{ content: response.content }}
+            />
+          </TabItem>
+        );
+      })}
+    </ApiTabs>
+  );
+};
+
+export default StatusCodes;