docusaurus-theme-openapi-docs 4.0.0 → 4.1.0

package/src/theme/ApiExplorer/CodeTabs/_CodeTabs.scss

@@ -146,6 +146,24 @@ body[class="ReactModal__Body--open"] {
   }
 }
 
+.openapi-tabs__code-item--dart {
+  color: var(--ifm-color-info);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/dart/dart-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-dart);
+    border-color: var(--openapi-code-tab-border-color-dart);
+  }
+}
+
 .openapi-tabs__code-item--javascript {
   color: var(--ifm-color-warning);
 
@@ -164,7 +182,7 @@ body[class="ReactModal__Body--open"] {
   }
 }
 
-.openapi-tabs__code-item--bash {
+.openapi-tabs__code-item--curl {
   color: var(--ifm-color-danger);
 
   &::after {
@@ -179,7 +197,7 @@ body[class="ReactModal__Body--open"] {
   }
 
   &.active {
-    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-bash);
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-curl);
     border-color: var(--ifm-color-danger);
   }
 }
@@ -220,6 +238,96 @@ body[class="ReactModal__Body--open"] {
   }
 }
 
+.openapi-tabs__code-item--r {
+  color: var(--ifm-color-gray-500);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/r/r-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-r);
+    border-color: var(--openapi-code-tab-border-color-r);
+  }
+}
+
+.openapi-tabs__code-item--swift {
+  color: var(--ifm-color-danger);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/swift/swift-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-swift);
+    border-color: var(--openapi-code-tab-border-color-swift);
+  }
+}
+
+.openapi-tabs__code-item--c {
+  color: var(--ifm-color-info);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/c/c-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-c);
+    border-color: var(--openapi-code-tab-border-color-c);
+  }
+}
+
+.openapi-tabs__code-item--objective-c {
+  color: var(--ifm-color-info);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/objectivec/objectivec-plain.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-objective-c);
+    border-color: var(--openapi-code-tab-border-color-objective-c);
+  }
+}
+
+.openapi-tabs__code-item--ocaml {
+  color: var(--ifm-color-warning);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/ocaml/ocaml-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-objective-ocaml);
+    border-color: var(--openapi-code-tab-border-color-objective-ocaml);
+  }
+}
+
 .openapi-tabs__code-item--nodejs {
   color: var(--ifm-color-success);
 
@@ -256,6 +364,42 @@ body[class="ReactModal__Body--open"] {
   }
 }
 
+.openapi-tabs__code-item--kotlin {
+  color: var(--ifm-color-gray-500);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/kotlin/kotlin-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-kotlin);
+    border-color: var(--openapi-code-tab-border-color-kotlin);
+  }
+}
+
+.openapi-tabs__code-item--rust {
+  color: var(--ifm-color-gray-500);
+
+  &::after {
+    content: "";
+    width: var(--code-tab-logo-width);
+    height: var(--code-tab-logo-height);
+    background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/rust/rust-original.svg")
+      no-repeat;
+    margin-block: auto;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-rust);
+    border-color: var(--openapi-code-tab-border-color-rust);
+  }
+}
+
 .openapi-tabs__code-item--java {
   color: var(--ifm-color-warning);
 

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React, { cloneElement, ReactElement } from "react";
+import React, { cloneElement, ReactElement, useEffect, useRef } from "react";
 
 import {
   sanitizeTabsChildren,
@@ -43,10 +43,38 @@ function TabList({
   selectValue,
   tabValues,
 }: CodeTabsProps & ReturnType<typeof useTabs>) {
-  const tabRefs: (HTMLLIElement | null)[] = [];
+  const tabRefs = useRef<(HTMLLIElement | null)[]>([]);
+  const tabsScrollContainerRef = useRef<any>();
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
 
+  useEffect(() => {
+    const activeTab = tabRefs.current.find(
+      (tab) => tab?.getAttribute("aria-selected") === "true"
+    );
+
+    if (activeTab && tabsScrollContainerRef.current) {
+      const container = tabsScrollContainerRef.current;
+      const containerRect = container.getBoundingClientRect();
+      const activeTabRect = activeTab.getBoundingClientRect();
+
+      // Calculate the distance to scroll to align active tab to the left
+      const glowOffset = 3;
+      const scrollOffset =
+        activeTabRect.left -
+        containerRect.left +
+        container.scrollLeft -
+        glowOffset;
+
+      // Check if the active tab is not already at the left position
+
+      if (Math.abs(scrollOffset - container.scrollLeft) > 4) {
+        // Adjust the scroll of the container
+        container.scrollLeft = scrollOffset;
+      }
+    }
+  }, []);
+
   const handleTabChange = (
     event:
       | React.FocusEvent<HTMLLIElement>
@@ -54,7 +82,7 @@ function TabList({
       | React.KeyboardEvent<HTMLLIElement>
   ) => {
     const newTab = event.currentTarget;
-    const newTabIndex = tabRefs.indexOf(newTab);
+    const newTabIndex = tabRefs.current.indexOf(newTab);
     const newTabValue = tabValues[newTabIndex]!.value;
 
     if (newTabValue !== selectedValue) {
@@ -80,7 +108,7 @@ function TabList({
         newLanguage = languageSet.filter(
           (lang: Language) => lang.language === newTabValue
         )[0];
-        action.setSelectedVariant(newLanguage.variant.toLowerCase());
+        action.setSelectedVariant(newLanguage.variants[0].toLowerCase());
         action.setSelectedSample(newLanguage.sample);
       }
       action.setLanguage(newLanguage);
@@ -96,13 +124,15 @@ function TabList({
         break;
       }
       case "ArrowRight": {
-        const nextTab = tabRefs.indexOf(event.currentTarget) + 1;
-        focusElement = tabRefs[nextTab] ?? tabRefs[0]!;
+        const nextTab = tabRefs.current.indexOf(event.currentTarget) + 1;
+        focusElement = tabRefs.current[nextTab] ?? tabRefs.current[0]!;
         break;
       }
       case "ArrowLeft": {
-        const prevTab = tabRefs.indexOf(event.currentTarget) - 1;
-        focusElement = tabRefs[prevTab] ?? tabRefs[tabRefs.length - 1]!;
+        const prevTab = tabRefs.current.indexOf(event.currentTarget) - 1;
+        focusElement =
+          tabRefs.current[prevTab] ??
+          tabRefs.current[tabRefs.current.length - 1]!;
         break;
       }
       default:
@@ -124,6 +154,7 @@ function TabList({
         },
         className
       )}
+      ref={tabsScrollContainerRef}
     >
       {tabValues.map(({ value, label, attributes }) => (
         <li
@@ -132,7 +163,7 @@ function TabList({
           tabIndex={selectedValue === value ? 0 : -1}
           aria-selected={selectedValue === value}
           key={value}
-          ref={(tabControl) => tabRefs.push(tabControl)}
+          ref={(tabControl) => tabRefs.current.push(tabControl)}
           onKeyDown={handleKeydown}
           onClick={handleTabChange}
           {...attributes}

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

@@ -8,8 +8,7 @@
 import React from "react";
 
 import BrowserOnly from "@docusaurus/BrowserOnly";
-
-import { useTypedSelector } from "../../ApiItem/hooks";
+import { useTypedSelector } from "@theme/ApiItem/hooks";
 
 function colorForMethod(method: string) {
   switch (method.toLowerCase()) {
@@ -35,13 +34,18 @@ function colorForMethod(method: string) {
 export interface Props {
   method: string;
   path: string;
+  context?: "endpoint" | "callback";
 }
 
-function MethodEndpoint({ method, path }: Props) {
+function MethodEndpoint({ method, path, context }: Props) {
   let serverValue = useTypedSelector((state: any) => state.server.value);
   let serverUrlWithVariables = "";
 
   const renderServerUrl = () => {
+    if (context === "callback") {
+      return "";
+    }
+
     if (serverValue && serverValue.variables) {
       serverUrlWithVariables = serverValue.url.replace(/\/$/, "");
 

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

@@ -80,6 +80,7 @@ function ParamOptions() {
       {optionalParams.length > 0 && (
         <>
           <button
+            type="button"
             className="openapi-explorer__show-more-btn"
             onClick={() => setShowOptional((prev) => !prev)}
           >

package/src/theme/ApiExplorer/Request/_Request.scss

@@ -114,6 +114,11 @@
   }
 }
 
+.openapi-security__summary-container {
+  background: var(--ifm-pre-background);
+  border-radius: var(--ifm-pre-border-radius);
+}
+
 // Prevent auto zoom on mobile iOS devices when focusing on input elmenents
 @media screen and (-webkit-min-device-pixel-ratio: 0) and (max-device-width: 1024px) {
   .prism-code,

package/src/theme/ApiExplorer/index.tsx

@@ -10,6 +10,7 @@ import React from "react";
 import CodeSnippets from "@theme/ApiExplorer/CodeSnippets";
 import Request from "@theme/ApiExplorer/Request";
 import Response from "@theme/ApiExplorer/Response";
+import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";
 import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 import sdk from "postman-collection";
 
@@ -24,6 +25,7 @@ function ApiExplorer({
 
   return (
     <>
+      <SecuritySchemes infoPath={infoPath} />
       {item.method !== "event" && (
         <CodeSnippets
           postman={postman}

package/src/theme/ApiItem/Layout/index.tsx

@@ -0,0 +1,82 @@
+/* ============================================================================
+ * 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 { useDoc } from "@docusaurus/plugin-content-docs/client";
+import { useWindowSize } from "@docusaurus/theme-common";
+import type { Props } from "@theme/ApiItem/Layout";
+import ContentVisibility from "@theme/ContentVisibility";
+import DocBreadcrumbs from "@theme/DocBreadcrumbs";
+import DocItemContent from "@theme/DocItem/Content";
+import DocItemFooter from "@theme/DocItem/Footer";
+import DocItemPaginator from "@theme/DocItem/Paginator";
+import DocItemTOCDesktop from "@theme/DocItem/TOC/Desktop";
+import DocItemTOCMobile from "@theme/DocItem/TOC/Mobile";
+import DocVersionBadge from "@theme/DocVersionBadge";
+import DocVersionBanner from "@theme/DocVersionBanner";
+import clsx from "clsx";
+
+import styles from "./styles.module.css";
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const { frontMatter, toc } = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+
+  const desktop =
+    canRender && (windowSize === "desktop" || windowSize === "ssr") ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({ children }: Props): JSX.Element {
+  const docTOC = useDocTOC();
+  const { metadata } = useDoc();
+  const { frontMatter } = useDoc();
+  const api = frontMatter.api;
+  return (
+    <div className="row">
+      <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
+        <ContentVisibility metadata={metadata} />
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <div className="row">
+              <div className={clsx("col", api ? "col--7" : "col--12")}>
+                <DocItemFooter />
+              </div>
+            </div>
+          </article>
+          <div className="row">
+            <div className={clsx("col", api ? "col--7" : "col--12")}>
+              <DocItemPaginator />
+            </div>
+          </div>
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/src/theme/ApiItem/Layout/styles.module.css

@@ -0,0 +1,17 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/src/theme/ApiItem/index.tsx

@@ -17,8 +17,8 @@ import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import { createAuth } from "@theme/ApiExplorer/Authorization/slice";
 import { createPersistanceMiddleware } from "@theme/ApiExplorer/persistanceMiddleware";
+import DocItemLayout from "@theme/ApiItem/Layout";
 import type { Props } from "@theme/DocItem";
-import DocItemLayout from "@theme/DocItem/Layout";
 import DocItemMetadata from "@theme/DocItem/Metadata";
 import clsx from "clsx";
 import { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";

package/src/theme/ParamsItem/index.tsx

@@ -14,6 +14,7 @@ import TabItem from "@theme/TabItem";
 import clsx from "clsx";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkGfm from "remark-gfm";
 
 import { createDescription } from "../../markdown/createDescription";
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
@@ -39,15 +40,49 @@ export interface Props {
     required: boolean;
     deprecated: boolean;
     schema: any;
+    enumDescriptions?: [string, string][];
   };
 }
 
-function ParamsItem({
-  param: { description, example, examples, name, required, schema, deprecated },
-}: Props) {
+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 "";
+};
+
+function ParamsItem({ param, ...rest }: Props) {
+  const {
+    description,
+    example,
+    examples,
+    name,
+    required,
+    deprecated,
+    enumDescriptions,
+  } = param;
+
+  let schema = param.schema;
+  let defaultValue: string | undefined;
+
   if (!schema || !schema?.type) {
     schema = { type: "any" };
   }
+  if (schema) {
+    if (schema.items) {
+      defaultValue = schema.items.default;
+    } else {
+      defaultValue = schema.default;
+    }
+  }
 
   const renderSchemaName = guard(schema, (schema) => (
     <span className="openapi-schema__type"> {getSchemaName(schema)}</span>
@@ -91,19 +126,43 @@ function ParamsItem({
     </div>
   ));
 
-  const renderDefaultValue = guard(
-    schema && schema.items
-      ? schema.items.default
-      : schema
-        ? schema.default
-        : undefined,
-    (value) => (
-      <div>
-        <ReactMarkdown children={`**Default value:** \`${value}\``} />
-      </div>
-    )
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <ReactMarkdown
+          rehypePlugins={[rehypeRaw]}
+          remarkPlugins={[remarkGfm]}
+          children={value}
+        />
+      );
+    }
   );
 
+  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;
+  }
+
   const renderExample = guard(toString(example), (example) => (
     <div>
       <strong>Example: </strong>
@@ -156,8 +215,9 @@ function ParamsItem({
         {renderDeprecated}
       </span>
       {renderSchema}
-      {renderDefaultValue}
       {renderDescription}
+      {renderEnumDescriptions}
+      {renderDefaultValue()}
       {renderExample}
       {renderExamples}
     </div>