docusaurus-theme-openapi-docs 1.0.0

package/lib/theme/ApiItem/index.js

@@ -0,0 +1,160 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = DocItem;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _ExecutionEnvironment = _interopRequireDefault(require("@docusaurus/ExecutionEnvironment"));
+
+var _themeCommon = require("@docusaurus/theme-common");
+
+var _DocBreadcrumbs = _interopRequireDefault(require("@theme/DocBreadcrumbs"));
+
+var _DocItemFooter = _interopRequireDefault(require("@theme/DocItemFooter"));
+
+var _DocPaginator = _interopRequireDefault(require("@theme/DocPaginator"));
+
+var _DocVersionBadge = _interopRequireDefault(require("@theme/DocVersionBadge"));
+
+var _DocVersionBanner = _interopRequireDefault(require("@theme/DocVersionBanner"));
+
+var _Heading = _interopRequireDefault(require("@theme/Heading"));
+
+var _MDXContent = _interopRequireDefault(require("@theme/MDXContent"));
+
+var _TOC = _interopRequireDefault(require("@theme/TOC"));
+
+var _TOCCollapsible = _interopRequireDefault(require("@theme/TOCCollapsible"));
+
+var _clsx = _interopRequireDefault(require("clsx"));
+
+var _stylesModule = _interopRequireDefault(require("./styles.module.css"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+let ApiDemoPanel = _ => <div style={{
+  marginTop: "3.5em"
+}} />;
+
+if (_ExecutionEnvironment.default.canUseDOM) {
+  ApiDemoPanel = require("@theme/ApiDemoPanel").default;
+}
+
+function DocItemMetadata(props) {
+  var _assets$image;
+
+  const {
+    content: DocContent
+  } = props;
+  const {
+    metadata,
+    frontMatter,
+    assets
+  } = DocContent;
+  const {
+    keywords
+  } = frontMatter;
+  const {
+    description,
+    title
+  } = metadata;
+  const image = (_assets$image = assets.image) !== null && _assets$image !== void 0 ? _assets$image : frontMatter.image;
+  return <_themeCommon.PageMetadata {...{
+    title,
+    description,
+    keywords,
+    image
+  }} />;
+}
+
+function DocItemContent(props) {
+  const {
+    content: DocContent
+  } = props;
+  const {
+    metadata,
+    frontMatter
+  } = DocContent;
+  const {
+    hide_title: hideTitle,
+    hide_table_of_contents: hideTableOfContents,
+    toc_min_heading_level: tocMinHeadingLevel,
+    toc_max_heading_level: tocMaxHeadingLevel
+  } = frontMatter;
+  const {
+    title
+  } = metadata;
+  const {
+    api
+  } = frontMatter; // We only add a title if:
+  // - user doesn't ask to hide it with front matter
+  // - the markdown content does not already contain a top-level h1 heading
+
+  const shouldAddTitle = !hideTitle && typeof DocContent.contentTitle === "undefined";
+  const windowSize = (0, _themeCommon.useWindowSize)();
+  const canRenderTOC = !hideTableOfContents && DocContent.toc && DocContent.toc.length > 0;
+  const renderTocDesktop = canRenderTOC && (windowSize === "desktop" || windowSize === "ssr");
+  return <div className="row">
+      <div className={(0, _clsx.default)("col", !hideTableOfContents && _stylesModule.default.docItemCol)}>
+        <_DocVersionBanner.default />
+        <div className={_stylesModule.default.docItemContainer}>
+          <article>
+            <_DocBreadcrumbs.default />
+            <_DocVersionBadge.default />
+
+            {canRenderTOC && <_TOCCollapsible.default toc={DocContent.toc} minHeadingLevel={tocMinHeadingLevel} maxHeadingLevel={tocMaxHeadingLevel} className={(0, _clsx.default)(_themeCommon.ThemeClassNames.docs.docTocMobile, _stylesModule.default.tocMobile)} />}
+
+            <div className={(0, _clsx.default)(_themeCommon.ThemeClassNames.docs.docMarkdown, "theme-api-markdown", "markdown")}>
+              {
+              /*
+               Title can be declared inside md content or declared through
+               front matter and added manually. To make both cases consistent,
+               the added title is added under the same div.markdown block
+               See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+               */
+            }
+              {shouldAddTitle && <header>
+                  <_Heading.default as="h1">{title}</_Heading.default>
+                </header>}
+              <_MDXContent.default>
+                <div className="row">
+                  <div className={(0, _clsx.default)("col", api ? "col--7" : "col--12")}>
+                    <DocContent />
+                  </div>
+                  {api && <div className="col col--5">
+                      <ApiDemoPanel item={api} />
+                    </div>}
+                </div>
+              </_MDXContent.default>
+            </div>
+            <div className={(0, _clsx.default)("col", api ? "col--7" : !canRenderTOC ? "col--9" : "col--12")}>
+              <_DocItemFooter.default {...props} />
+            </div>
+          </article>
+          <div className={(0, _clsx.default)("col", api ? "col--7" : !canRenderTOC ? "col--9" : "col--12")}>
+            <_DocPaginator.default previous={metadata.previous} next={metadata.next} />
+          </div>
+        </div>
+      </div>
+      {renderTocDesktop && <div className="col col--3">
+          <_TOC.default toc={DocContent.toc} minHeadingLevel={tocMinHeadingLevel} maxHeadingLevel={tocMaxHeadingLevel} className={_themeCommon.ThemeClassNames.docs.docTocDesktop} />
+        </div>}
+    </div>;
+}
+
+function DocItem(props) {
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
+  return <_themeCommon.HtmlClassNameProvider className={docHtmlClassName}>
+      <DocItemMetadata {...props} />
+      <DocItemContent {...props} />
+    </_themeCommon.HtmlClassNameProvider>;
+}

package/lib/theme/ApiItem/styles.module.css

@@ -0,0 +1,109 @@
+:root {
+  --openapi-required: var(--ifm-color-danger);
+}
+
+.apiItemContainer article > *:first-child,
+.apiItemContainer header + * {
+  margin-top: 0;
+}
+
+/* default markdown margins look really silly in a table */
+:global(.theme-api-markdown table *:last-child) {
+  margin-bottom: 0;
+}
+
+:global(.theme-api-markdown details) {
+  margin: unset;
+  max-width: 600px;
+  background-color: transparent;
+  color: var(--ifm-font-color-base);
+  padding: unset;
+  border: unset !important;
+  box-shadow: unset !important;
+  --docusaurus-details-decoration-color: var(--ifm-font-color-base);
+}
+
+:global(.theme-api-markdown details > div > div) {
+  padding-top: unset !important;
+  border-top: unset !important;
+}
+
+:global(.theme-api-markdown code) {
+  max-width: 600px;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+
+  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+  .tocMobile {
+    display: none;
+  }
+}
+
+:global(.theme-api-markdown details li) {
+  list-style: none;
+  padding-bottom: 5px;
+  padding-top: 5px;
+}
+
+:global(.theme-api-markdown details li:last-child) {
+  border-left: none;
+}
+
+:global(.theme-api-markdown details p) {
+  margin-bottom: 0;
+}
+
+:global(.theme-api-markdown li::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(--ifm-color-gray-500);
+  content: "";
+  display: inline-block;
+}
+
+:global(.theme-api-markdown details ul) {
+  padding-left: 0;
+  /* font-family: "Fira Mono", monospace; */
+  font-size: 14px;
+}
+
+:global(.theme-api-markdown h2) {
+  font-size: 2rem;
+}
+
+:global(.schemaItem) {
+  list-style: none;
+  position: relative;
+  margin: 0 !important;
+  padding: 5px 0 5px 1rem;
+  border-left: thin solid var(--ifm-color-gray-500) !important;
+}
+
+:global(.schemaItem:hover) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.schemaItem:focus) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.paramsItem:hover) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.paramsItem:focus) {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+:global(.theme-api-markdown div[class^="collapsibleContent"]) {
+  margin-top: 0 !important;
+  padding-left: 2px;
+}

package/lib/theme/ParamsItem/index.js

@@ -0,0 +1,68 @@
+/* ============================================================================
+ * 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 ReactMarkdown from "react-markdown";
+
+import { createDescription } from "../../markdown/createDescription";
+import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
+import { guard } from "../../markdown/utils";
+import styles from "./styles.module.css";
+
+function ParamsItem({
+  param: { description, example, examples, name, required, schema },
+}) {
+  const renderSchemaName = guard(schema, (schema) => (
+    <span className={styles.schemaName}> {getSchemaName(schema)}</span>
+  ));
+
+  const renderSchemaRequired = guard(required, () => (
+    <strong className={styles.paramsRequired}> required</strong>
+  ));
+
+  const renderSchema = guard(getQualifierMessage(schema), (message) => (
+    <div>
+      <ReactMarkdown children={createDescription(message)} />
+    </div>
+  ));
+
+  const renderDescription = guard(description, (description) => (
+    <div>
+      <ReactMarkdown children={createDescription(description)} />
+    </div>
+  ));
+
+  const renderExample = guard(example, (example) => (
+    <div>{`Example: ${example}`}</div>
+  ));
+
+  const renderExamples = guard(examples, (examples) => {
+    const exampleEntries = Object.entries(examples);
+    return (
+      <>
+        {exampleEntries.map(([k, v]) => (
+          <div>{`Example (${k}): ${v.value}`}</div>
+        ))}
+      </>
+    );
+  });
+
+  return (
+    <li className={styles.paramsItem}>
+      <strong>{name}</strong>
+      {renderSchemaName}
+      {renderSchemaRequired}
+      {renderSchema}
+      {renderDescription}
+      {renderExample}
+      {renderExamples}
+    </li>
+  );
+}
+
+export default ParamsItem;

package/lib/theme/ParamsItem/styles.module.css

@@ -0,0 +1,24 @@
+.paramsItem {
+  margin: 0 0 0 1rem !important;
+  position: relative;
+  padding-left: 1rem;
+  border-left: thin solid var(--ifm-color-gray-500) !important;
+  margin-top: unset !important;
+}
+
+.paramsItem:hover {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.paramsItem:focus {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.schemaName {
+  opacity: 0.6;
+}
+
+.paramsRequired {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-required);
+}

package/lib/theme/SchemaItem/index.js

@@ -0,0 +1,58 @@
+/* ============================================================================
+ * 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 ReactMarkdown from "react-markdown";
+
+import { createDescription } from "../../markdown/createDescription";
+import { guard } from "../../markdown/utils";
+import styles from "./styles.module.css";
+
+function SchemaItem({
+  children: collapsibleSchemaContent,
+  collapsible,
+  name,
+  qualifierMessage,
+  required,
+  schemaDescription,
+  schemaName,
+}) {
+  const renderRequired = guard(required, () => (
+    <strong className={styles.required}> required</strong>
+  ));
+
+  const renderSchemaDescription = guard(schemaDescription, (description) => (
+    <div className={styles.schemaDescription}>
+      <ReactMarkdown children={createDescription(description)} />
+    </div>
+  ));
+
+  const renderQualifierMessage = guard(qualifierMessage, (message) => (
+    <div className={styles.schemaQualifierMessage}>
+      <ReactMarkdown children={createDescription(message)} />
+    </div>
+  ));
+
+  const schemaContent = (
+    <div>
+      <strong>{name}</strong>
+      <span className={styles.schemaName}> {schemaName}</span>
+      {renderRequired}
+      {renderQualifierMessage}
+      {renderSchemaDescription}
+    </div>
+  );
+
+  return (
+    <li className={styles.schemaItem}>
+      {collapsible ? collapsibleSchemaContent : schemaContent}
+    </li>
+  );
+}
+
+export default SchemaItem;

package/lib/theme/SchemaItem/styles.module.css

@@ -0,0 +1,24 @@
+.schemaItem {
+  list-style: none;
+  position: relative;
+  margin: 0 !important;
+  padding: 5px 0 5px 1rem;
+  border-left: thin solid var(--ifm-color-gray-500) !important;
+}
+
+.schemaItem:hover {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.schemaItem:focus {
+  background-color: var(--ifm-menu-color-background-active);
+}
+
+.schemaName {
+  opacity: 0.6;
+}
+
+.required {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-required);
+}

package/lib/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}
+    />
+  );
+}