docusaurus-theme-openapi-docs 4.1.0 → 4.2.0

package/lib/theme/SchemaItem/index.d.ts

@@ -1,12 +1,12 @@
 import React, { ReactNode } from "react";
 export interface Props {
-    children: ReactNode;
-    collapsible: boolean;
-    name: string;
-    qualifierMessage: string | undefined;
-    required: boolean;
-    schemaName: string;
-    schema: any;
-    discriminator: boolean;
+    children?: ReactNode;
+    collapsible?: boolean;
+    name?: string;
+    qualifierMessage?: string | undefined;
+    required?: boolean;
+    schemaName?: string;
+    schema?: any;
+    discriminator?: boolean;
 }
 export default function SchemaItem(props: Props): React.JSX.Element;

package/lib/theme/SchemaItem/index.js

@@ -88,11 +88,15 @@ function SchemaItem(props) {
   const renderEnumDescriptions = (0, utils_1.guard)(
     getEnumDescriptionMarkdown(enumDescriptions),
     (value) => {
-      return react_1.default.createElement(react_markdown_1.default, {
-        remarkPlugins: [remark_gfm_1.default],
-        rehypePlugins: [rehype_raw_1.default],
-        children: value,
-      });
+      return react_1.default.createElement(
+        "div",
+        { style: { marginTop: ".5rem" } },
+        react_1.default.createElement(react_markdown_1.default, {
+          remarkPlugins: [remark_gfm_1.default],
+          rehypePlugins: [rehype_raw_1.default],
+          children: value,
+        })
+      );
     }
   );
   const renderSchemaDescription = (0, utils_1.guard)(

package/lib/theme/SkeletonLoader/index.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+interface Props {
+    size?: "sm" | "md" | "lg";
+}
+declare const SkeletonLoader: React.FC<Props>;
+export default SkeletonLoader;

package/lib/theme/SkeletonLoader/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+const SkeletonLoader = (props) => {
+  return react_1.default.createElement("div", {
+    className: `openapi-skeleton ${props.size ?? "md"}`,
+  });
+};
+exports.default = SkeletonLoader;

package/lib/theme/StatusCodes/index.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/lib/types";
+interface Props {
+    id?: string;
+    label?: string;
+    responses: ApiItem["responses"];
+}
+declare const StatusCodes: React.FC<Props>;
+export default StatusCodes;

package/lib/theme/StatusCodes/index.js

@@ -0,0 +1,78 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+const ApiTabs_1 = __importDefault(require("@theme/ApiTabs"));
+const Details_1 = __importDefault(require("@theme/Details"));
+const ResponseExamples_1 = require("@theme/ResponseExamples");
+const ResponseSchema_1 = __importDefault(require("@theme/ResponseSchema"));
+const TabItem_1 = __importDefault(require("@theme/TabItem"));
+const createDescription_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/createDescription");
+const StatusCodes = ({ label, id, responses }) => {
+  if (!responses) return null;
+  const codes = Object.keys(responses);
+  if (codes.length === 0) return null;
+  return react_1.default.createElement(
+    ApiTabs_1.default,
+    { label: label, id: id },
+    codes.map((code) => {
+      const response = responses[code];
+      const responseHeaders = response.headers;
+      return (
+        // @ts-ignore
+        react_1.default.createElement(
+          TabItem_1.default,
+          { key: code, label: code, value: code },
+          react_1.default.createElement(
+            "div",
+            null,
+            response.description &&
+              react_1.default.createElement(
+                "div",
+                { style: { marginTop: ".5rem", marginBottom: ".5rem" } },
+                (0, createDescription_1.createDescription)(response.description)
+              )
+          ),
+          responseHeaders &&
+            react_1.default.createElement(
+              Details_1.default,
+              {
+                className: "openapi-markdown__details",
+                "data-collapsed": true,
+                open: false,
+                style: { textAlign: "left", marginBottom: "1rem" },
+                summary: react_1.default.createElement(
+                  "summary",
+                  null,
+                  react_1.default.createElement(
+                    "strong",
+                    null,
+                    "Response Headers"
+                  )
+                ),
+              },
+              react_1.default.createElement(
+                ResponseExamples_1.ResponseHeaders,
+                { responseHeaders: responseHeaders }
+              )
+            ),
+          react_1.default.createElement(ResponseSchema_1.default, {
+            title: "Schema",
+            body: { content: response.content },
+          })
+        )
+      );
+    })
+  );
+};
+exports.default = StatusCodes;

package/lib/theme/styles.scss

@@ -81,6 +81,7 @@
   --openapi-explorer-padding-input: 0.5rem;
   --openapi-explorer-border-color: var(--ifm-toc-border-color);
   --openapi-explorer-caret-bg: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="16px" height="16px" viewBox="0 0 24 24"><path d="M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6-6 6z"></path></svg>');
+  --openapi-skeleton-background: var(--ifm-color-emphasis-100);
 }
 
 [data-theme="dark"] {
@@ -92,16 +93,16 @@
   height: 100%;
 }
 
-@media (min-width: 997px) {
-  .docItemCol {
-    max-width: 75% !important;
-  }
+// @media (min-width: 997px) {
+//   .docItemCol {
+//     max-width: 75% !important;
+//   }
 
-  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
-  .tocMobile {
-    display: none;
-  }
-}
+//   /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+//   .tocMobile {
+//     display: none;
+//   }
+// }
 
 /* Begin OpenAPI theme styles */
 // [data-theme="dark"] {
@@ -160,6 +161,52 @@
   border-right: thin solid var(--ifm-toc-border-color);
 }
 
+@media (max-width: 997px) {
+  .schema {
+    margin-bottom: 1rem;
+  }
+}
+
 .openapi-tabs__heading {
   margin-bottom: 1rem;
 }
+
+/* Loading Skeleton */
+@keyframes pulsing {
+  0% {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-100);
+  }
+  50% {
+    opacity: 0.6;
+    background-color: var(--ifm-toc-border-color);
+  }
+  100% {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-100);
+  }
+}
+
+.openapi-skeleton {
+  animation: pulsing 2s infinite ease-in-out;
+}
+
+/* Loading Skeleton */
+.openapi-skeleton {
+  border-radius: var(--ifm-pre-border-radius);
+  background-color: var(--openapi-skeleton-background);
+  max-width: 100%;
+  margin: 1rem auto;
+}
+
+.openapi-skeleton.sm {
+  height: 100px;
+}
+
+.openapi-skeleton.md {
+  height: 350px;
+}
+
+.openapi-skeleton.lg {
+  height: 96.5%;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -39,10 +39,11 @@
     "@docusaurus/theme-common": "^3.5.0",
     "@hookform/error-message": "^2.0.1",
     "@reduxjs/toolkit": "^1.7.1",
+    "allof-merge": "^0.6.6",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.1.0",
     "crypto-js": "^4.1.1",
-    "docusaurus-plugin-openapi-docs": "^4.1.0",
+    "docusaurus-plugin-openapi-docs": "^4.2.0",
     "docusaurus-plugin-sass": "^0.2.3",
     "file-saver": "^2.0.5",
     "lodash": "^4.17.20",
@@ -58,8 +59,8 @@
     "react-redux": "^7.2.0",
     "rehype-raw": "^6.1.1",
     "remark-gfm": "3.0.1",
-    "sass": "^1.58.1",
-    "sass-loader": "^13.3.2",
+    "sass": "^1.80.4",
+    "sass-loader": "^16.0.2",
     "webpack": "^5.61.0",
     "xml-formatter": "^2.6.1"
   },
@@ -70,5 +71,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "4e771d309f6defe395449b26cc3c65814d72cbcc"
+  "gitHead": "e7295a8aa6f3fab5ccc4f8f9ad0e6c33d785aa16"
 }

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

@@ -180,7 +180,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
   ]);
   // no dependencies was intentionlly set for this particular hook. it's safe as long as if conditions are set
   useEffect(function onSelectedVariantUpdate() {
-    if (selectedVariant && selectedVariant !== language.variant) {
+    if (selectedVariant && selectedVariant !== language?.variant) {
       const postmanRequest = buildPostmanRequest(postman, {
         queryParams,
         pathParams,
@@ -211,6 +211,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(function onSelectedSampleUpdate() {
     if (
+      language &&
       language.samples &&
       language.samplesSources &&
       selectedSample &&

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

@@ -436,6 +436,56 @@ body[class="ReactModal__Body--open"] {
   }
 }
 
+.openapi-tabs__code-item--http {
+  color: var(--ifm-color-gray-500);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+
+  &::after {
+    content: "";
+    display: inline-block;
+    width: 32px; /* Explicitly setting width to 32 pixels */
+    height: 32px; /* Explicitly setting height to 32 pixels */
+    background-image: url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDIyTDggMTZMMTIgMTBNMjAgMjJMMjQgMTZMIDIwIDEwIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=");
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center; /* Center the SVG */
+    margin-top: 0.5rem;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--opeanpi-code-tab-shadow-color-http);
+    border-color: var(--openapi-code-tab-border-color-http);
+  }
+}
+
+.openapi-tabs__code-item--shell {
+  color: var(--ifm-color-gray-500);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+
+  &::after {
+    content: "";
+    display: inline-block;
+    width: 32px; /* Explicitly setting width to 32 pixels */
+    height: 32px; /* Explicitly setting height to 32 pixels */
+    background-image: url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDIyTDggMTZMMTIgMTBNMjAgMjJMMjQgMTZMIDIwIDEwIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=");
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center; /* Center the SVG */
+    margin-top: 0.5rem;
+  }
+
+  &.active {
+    box-shadow: 0 0 0 3px var(--opeanpi-code-tab-shadow-color-shell);
+    border-color: var(--openapi-code-tab-border-color-shell);
+  }
+}
+
 @media only screen and (min-width: 768px) and (max-width: 996px) {
   .openapi-tabs__code-list {
     justify-content: space-around;

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

@@ -52,6 +52,7 @@ export default function DocItemLayout({ children }: Props): JSX.Element {
   const { metadata } = useDoc();
   const { frontMatter } = useDoc();
   const api = frontMatter.api;
+  const schema = frontMatter.schema;
   return (
     <div className="row">
       <div className={clsx("col", !docTOC.hidden && styles.docItemCol)}>
@@ -64,13 +65,15 @@ export default function DocItemLayout({ children }: Props): JSX.Element {
             {docTOC.mobile}
             <DocItemContent>{children}</DocItemContent>
             <div className="row">
-              <div className={clsx("col", api ? "col--7" : "col--12")}>
+              <div
+                className={clsx("col", api || schema ? "col--7" : "col--12")}
+              >
                 <DocItemFooter />
               </div>
             </div>
           </article>
           <div className="row">
-            <div className={clsx("col", api ? "col--7" : "col--12")}>
+            <div className={clsx("col", api || schema ? "col--7" : "col--12")}>
               <DocItemPaginator />
             </div>
           </div>

package/src/theme/ApiItem/index.tsx

@@ -18,8 +18,10 @@ 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 CodeBlock from "@theme/CodeBlock";
 import type { Props } from "@theme/DocItem";
 import DocItemMetadata from "@theme/DocItem/Metadata";
+import SkeletonLoader from "@theme/SkeletonLoader";
 import clsx from "clsx";
 import { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -46,6 +48,10 @@ interface SchemaFrontMatter extends DocFrontMatter {
   readonly schema?: boolean;
 }
 
+interface SampleFrontMatter extends DocFrontMatter {
+  readonly sample?: any;
+}
+
 // @ts-ignore
 export default function ApiItem(props: Props): JSX.Element {
   const docHtmlClassName = `docs-doc-id-${props.content.metadata.id}`;
@@ -54,6 +60,7 @@ export default function ApiItem(props: Props): JSX.Element {
   const { info_path: infoPath } = frontMatter as DocFrontMatter;
   let { api } = frontMatter as ApiFrontMatter;
   const { schema } = frontMatter as SchemaFrontMatter;
+  const { sample } = frontMatter as SampleFrontMatter;
   // decompress and parse
   if (api) {
     try {
@@ -152,7 +159,7 @@ export default function ApiItem(props: Props): JSX.Element {
                   <MDXComponent />
                 </div>
                 <div className="col col--5 openapi-right-panel__container">
-                  <BrowserOnly fallback={<div>Loading...</div>}>
+                  <BrowserOnly fallback={<SkeletonLoader size="lg" />}>
                     {() => {
                       return <ApiExplorer item={api} infoPath={infoPath} />;
                     }}
@@ -171,9 +178,14 @@ export default function ApiItem(props: Props): JSX.Element {
           <DocItemMetadata />
           <DocItemLayout>
             <div className={clsx("row", "theme-api-markdown")}>
-              <div className="col col--12">
+              <div className="col col--7 openapi-left-panel__container schema">
                 <MDXComponent />
               </div>
+              <div className="col col--5 openapi-right-panel__container">
+                <CodeBlock language="json" title={`${frontMatter.title}`}>
+                  {JSON.stringify(sample, null, 2)}
+                </CodeBlock>
+              </div>
             </div>
           </DocItemLayout>
         </HtmlClassNameProvider>

package/src/theme/ApiTabs/_ApiTabs.scss

@@ -6,7 +6,6 @@
  * ========================================================================== */
 .openapi-tabs__container {
   margin-left: -1px;
-  margin-bottom: var(--ifm-leading);
 }
 
 .openapi-tabs__response-header {

package/src/theme/ArrayBrackets/index.tsx

@@ -0,0 +1,37 @@
+/* ============================================================================
+ * 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";
+
+export const OpeningArrayBracket = () => (
+  <li>
+    <div
+      style={{
+        fontSize: "var(--ifm-code-font-size)",
+        opacity: 0.6,
+        marginLeft: "-.5rem",
+        paddingBottom: ".5rem",
+      }}
+    >
+      Array [
+    </div>
+  </li>
+);
+
+export const ClosingArrayBracket = () => (
+  <li>
+    <div
+      style={{
+        fontSize: "var(--ifm-code-font-size)",
+        opacity: 0.6,
+        marginLeft: "-.5rem",
+      }}
+    >
+      ]
+    </div>
+  </li>
+);

package/src/theme/ParamsDetails/index.tsx

@@ -0,0 +1,88 @@
+/* ============================================================================
+ * 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, { Suspense } from "react";
+
+import BrowserOnly from "@docusaurus/BrowserOnly";
+import Details from "@theme/Details";
+import ParamsItem from "@theme/ParamsItem";
+import SkeletonLoader from "@theme/SkeletonLoader";
+
+interface Props {
+  parameters: any[];
+}
+
+const ParamsDetailsComponent: React.FC<Props> = ({ parameters }) => {
+  const types = ["path", "query", "header", "cookie"];
+
+  return (
+    <>
+      {types.map((type) => {
+        const params = parameters?.filter((param: any) => param?.in === type);
+
+        if (!params || params.length === 0) {
+          return null;
+        }
+
+        const summaryElement = (
+          <summary>
+            <h3 className="openapi-markdown__details-summary-header-params">
+              {`${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`}
+            </h3>
+          </summary>
+        );
+
+        return (
+          <Details
+            key={type}
+            className="openapi-markdown__details"
+            style={{ marginBottom: "1rem" }}
+            data-collapsed={false}
+            open={true}
+            summary={summaryElement}
+          >
+            <ul>
+              {params.map((param: any, index: number) => (
+                <ParamsItem
+                  key={index}
+                  className="paramsItem"
+                  param={{
+                    ...param,
+                    enumDescriptions: Object.entries(
+                      param?.schema?.["x-enumDescriptions"] ??
+                        param?.schema?.items?.["x-enumDescriptions"] ??
+                        {}
+                    ),
+                  }}
+                />
+              ))}
+            </ul>
+          </Details>
+        );
+      })}
+    </>
+  );
+};
+
+const ParamsDetails: React.FC<Props> = (props) => {
+  return (
+    <BrowserOnly fallback={<SkeletonLoader size="sm" />}>
+      {() => {
+        const LazyComponent = React.lazy(() =>
+          Promise.resolve({ default: ParamsDetailsComponent })
+        );
+        return (
+          <Suspense fallback={null}>
+            <LazyComponent {...props} />
+          </Suspense>
+        );
+      }}
+    </BrowserOnly>
+  );
+};
+
+export default ParamsDetails;

package/src/theme/ParamsItem/index.tsx

@@ -32,6 +32,7 @@ export interface ExampleObject {
 }
 
 export interface Props {
+  className: string;
   param: {
     description: string;
     example: any;
@@ -106,7 +107,7 @@ function ParamsItem({ param, ...rest }: Props) {
   ));
 
   const renderDescription = guard(description, (description) => (
-    <div>
+    <>
       <ReactMarkdown
         children={createDescription(description)}
         components={{
@@ -123,18 +124,20 @@ function ParamsItem({ param, ...rest }: Props) {
         }}
         rehypePlugins={[rehypeRaw]}
       />
-    </div>
+    </>
   ));
 
   const renderEnumDescriptions = guard(
     getEnumDescriptionMarkdown(enumDescriptions),
     (value) => {
       return (
-        <ReactMarkdown
-          rehypePlugins={[rehypeRaw]}
-          remarkPlugins={[remarkGfm]}
-          children={value}
-        />
+        <div style={{ marginTop: ".5rem" }}>
+          <ReactMarkdown
+            rehypePlugins={[rehypeRaw]}
+            remarkPlugins={[remarkGfm]}
+            children={value}
+          />
+        </div>
       );
     }
   );