docusaurus-theme-openapi-docs 4.0.1 → 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({ children: collapsibleSchemaContent, collapsible, name, qualifierMessage, required, schemaName, schema, }: Props): React.JSX.Element;
+export default function SchemaItem(props: Props): React.JSX.Element;

package/lib/theme/SchemaItem/index.js

@@ -16,25 +16,50 @@ const CodeBlock_1 = __importDefault(require("@theme/CodeBlock"));
 const clsx_1 = __importDefault(require("clsx"));
 const react_markdown_1 = __importDefault(require("react-markdown"));
 const rehype_raw_1 = __importDefault(require("rehype-raw"));
+const remark_gfm_1 = __importDefault(require("remark-gfm"));
 const createDescription_1 = require("../../markdown/createDescription");
 const utils_1 = require("../../markdown/utils");
-function SchemaItem({
-  children: collapsibleSchemaContent,
-  collapsible,
-  name,
-  qualifierMessage,
-  required,
-  schemaName,
-  schema,
-}) {
+const transformEnumDescriptions = (enumDescriptions) => {
+  if (enumDescriptions) {
+    return Object.entries(enumDescriptions);
+  }
+  return [];
+};
+const getEnumDescriptionMarkdown = (enumDescriptions) => {
+  if (enumDescriptions?.length) {
+    return `| Enum Value | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+  return "";
+};
+function SchemaItem(props) {
+  const {
+    children: collapsibleSchemaContent,
+    collapsible,
+    name,
+    qualifierMessage,
+    required,
+    schemaName,
+    schema,
+  } = props;
   let deprecated;
   let schemaDescription;
   let defaultValue;
+  let example;
   let nullable;
+  let enumDescriptions = [];
   if (schema) {
     deprecated = schema.deprecated;
     schemaDescription = schema.description;
+    enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
+    example = schema.example;
     nullable = schema.nullable;
   }
   const renderRequired = (0, utils_1.guard)(
@@ -60,6 +85,20 @@ function SchemaItem({
       "nullable"
     )
   );
+  const renderEnumDescriptions = (0, utils_1.guard)(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (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)(
     schemaDescription,
     (description) =>
@@ -103,15 +142,64 @@ function SchemaItem({
         })
       )
   );
-  const renderDefaultValue = (0, utils_1.guard)(defaultValue, (value) =>
-    react_1.default.createElement(
-      "div",
-      { className: "" },
-      react_1.default.createElement(react_markdown_1.default, {
-        children: `**Default value:** \`${value}\``,
-      })
-    )
-  );
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return react_1.default.createElement(
+          "div",
+          null,
+          react_1.default.createElement("strong", null, "Default value: "),
+          react_1.default.createElement(
+            "span",
+            null,
+            react_1.default.createElement("code", null, defaultValue)
+          )
+        );
+      }
+      return react_1.default.createElement(
+        "div",
+        null,
+        react_1.default.createElement("strong", null, "Default value: "),
+        react_1.default.createElement(
+          "span",
+          null,
+          react_1.default.createElement(
+            "code",
+            null,
+            JSON.stringify(defaultValue)
+          )
+        )
+      );
+    }
+    return undefined;
+  }
+  function renderExample() {
+    if (example !== undefined) {
+      if (typeof example === "string") {
+        return react_1.default.createElement(
+          "div",
+          null,
+          react_1.default.createElement("strong", null, "Example: "),
+          react_1.default.createElement(
+            "span",
+            null,
+            react_1.default.createElement("code", null, example)
+          )
+        );
+      }
+      return react_1.default.createElement(
+        "div",
+        null,
+        react_1.default.createElement("strong", null, "Example: "),
+        react_1.default.createElement(
+          "span",
+          null,
+          react_1.default.createElement("code", null, JSON.stringify(example))
+        )
+      );
+    }
+    return undefined;
+  }
   const schemaContent = react_1.default.createElement(
     "div",
     null,
@@ -141,9 +229,11 @@ function SchemaItem({
       renderRequired,
       renderDeprecated
     ),
-    renderQualifierMessage,
-    renderDefaultValue,
     renderSchemaDescription,
+    renderEnumDescriptions,
+    renderQualifierMessage,
+    renderDefaultValue(),
+    renderExample(),
     collapsibleSchemaContent ?? collapsibleSchemaContent
   );
   return react_1.default.createElement(

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.0.1",
+  "version": "4.2.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,7 +28,7 @@
     "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\""
   },
   "devDependencies": {
-    "@docusaurus/types": "^3.0.1",
+    "@docusaurus/types": "^3.5.0",
     "@types/crypto-js": "^4.1.0",
     "@types/file-saver": "^2.0.5",
     "@types/lodash": "^4.14.176",
@@ -36,13 +36,14 @@
     "eslint-plugin-prettier": "^5.0.1"
   },
   "dependencies": {
-    "@docusaurus/theme-common": "^3.0.1",
+    "@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.0.1",
+    "docusaurus-plugin-openapi-docs": "^4.2.0",
     "docusaurus-plugin-sass": "^0.2.3",
     "file-saver": "^2.0.5",
     "lodash": "^4.17.20",
@@ -57,8 +58,9 @@
     "react-modal": "^3.15.1",
     "react-redux": "^7.2.0",
     "rehype-raw": "^6.1.1",
-    "sass": "^1.58.1",
-    "sass-loader": "^13.3.2",
+    "remark-gfm": "3.0.1",
+    "sass": "^1.80.4",
+    "sass-loader": "^16.0.2",
     "webpack": "^5.61.0",
     "xml-formatter": "^2.6.1"
   },
@@ -69,5 +71,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e228de93d24062c46fb206548dca7af9bc6264bb"
+  "gitHead": "e7295a8aa6f3fab5ccc4f8f9ad0e6c33d785aa16"
 }

package/src/markdown/utils.ts

@@ -7,9 +7,10 @@
 
 import { ReactNode } from "react";
 
-export type Children = ReactNode | string | undefined | (string | undefined)[];
+/** @deprecated use ReactNode from React instead */
+export type Children = ReactNode;
 
-export type Props = Record<string, any> & { children?: Children };
+export type Props = Record<string, any> & { children?: ReactNode };
 
 export function create(tag: string, props: Props): string {
   const { children, ...rest } = props;
@@ -24,8 +25,8 @@ export function create(tag: string, props: Props): string {
 
 export function guard<T>(
   value: T | undefined | string,
-  cb: (value: T) => Children
-): string {
+  cb: (value: T) => ReactNode
+) {
   if (!!value || value === 0) {
     const children = cb(value as T);
     return render(children);
@@ -33,11 +34,11 @@ export function guard<T>(
   return "";
 }
 
-export function render(children: Children): string {
+export function render(children: ReactNode) {
   if (Array.isArray(children)) {
     return children.filter((c) => c !== undefined).join("");
   }
-  return (children as string) ?? "";
+  return children ?? "";
 }
 
 export function toString(value: any): string | undefined {

package/src/plugin-content-docs.d.ts

@@ -15,4 +15,6 @@ declare module "@docusaurus/plugin-content-docs/client" {
     children: ReactNode;
     content: PropDocContent;
   });
+
+  export function useDoc();
 }

package/src/theme/ApiExplorer/CodeSnippets/code-snippets-types.ts

@@ -22,10 +22,12 @@ export type CodeSampleLanguage =
   | "JavaScript"
   | "Kotlin"
   | "Objective-C"
+  | "OCaml"
   | "Perl"
   | "PHP"
   | "PowerShell"
   | "Python"
+  | "R"
   | "Ruby"
   | "Rust"
   | "Scala"

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

@@ -27,120 +27,10 @@ import {
   getCodeSampleSourceFromLanguage,
   mergeArraysbyLanguage,
   mergeCodeSampleLanguage,
+  generateLanguageSet,
 } from "./languages";
 
-export const languageSet: Language[] = [
-  {
-    highlight: "bash",
-    language: "curl",
-    codeSampleLanguage: "Shell",
-    logoClass: "bash",
-    options: {
-      longFormat: false,
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "cURL",
-    variants: ["curl"],
-  },
-  {
-    highlight: "python",
-    language: "python",
-    codeSampleLanguage: "Python",
-    logoClass: "python",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "requests",
-    variants: ["requests", "http.client"],
-  },
-  {
-    highlight: "go",
-    language: "go",
-    codeSampleLanguage: "Go",
-    logoClass: "go",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "native",
-    variants: ["native"],
-  },
-  {
-    highlight: "javascript",
-    language: "nodejs",
-    codeSampleLanguage: "JavaScript",
-    logoClass: "nodejs",
-    options: {
-      ES6_enabled: true,
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "axios",
-    variants: ["axios", "native"],
-  },
-  {
-    highlight: "ruby",
-    language: "ruby",
-    codeSampleLanguage: "Ruby",
-    logoClass: "ruby",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "Net::HTTP",
-    variants: ["net::http"],
-  },
-  {
-    highlight: "csharp",
-    language: "csharp",
-    codeSampleLanguage: "C#",
-    logoClass: "csharp",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "RestSharp",
-    variants: ["restsharp", "httpclient"],
-  },
-  {
-    highlight: "php",
-    language: "php",
-    codeSampleLanguage: "PHP",
-    logoClass: "php",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "cURL",
-    variants: ["curl", "guzzle", "pecl_http", "http_request2"],
-  },
-  {
-    highlight: "java",
-    language: "java",
-    codeSampleLanguage: "Java",
-    logoClass: "java",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "OkHttp",
-    variants: ["okhttp", "unirest"],
-  },
-  {
-    highlight: "powershell",
-    language: "powershell",
-    codeSampleLanguage: "PowerShell",
-    logoClass: "powershell",
-    options: {
-      followRedirect: true,
-      trimRequestBody: true,
-    },
-    variant: "RestMethod",
-    variants: ["restmethod"],
-  },
-];
+export const languageSet: Language[] = generateLanguageSet();
 
 export interface Props {
   postman: sdk.Request;
@@ -290,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,
@@ -321,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 &&
@@ -339,6 +230,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
 
   return (
     <>
+      {/* Outer language tabs */}
       <CodeTabs
         groupId="code-samples"
         action={{
@@ -347,6 +239,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
           setSelectedSample: setSelectedSample,
         }}
         languageSet={mergedLangs}
+        defaultValue={defaultLang[0]?.language ?? mergedLangs[0].language}
         lazy
       >
         {mergedLangs.map((lang) => {
@@ -359,6 +252,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
                 className: `openapi-tabs__code-item--${lang.logoClass}`,
               }}
             >
+              {/* Inner x-codeSamples tabs */}
               {lang.samples && (
                 <CodeTabs
                   className="openapi-tabs__code-container-inner"
@@ -400,6 +294,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
                 </CodeTabs>
               )}
 
+              {/* Inner generated code snippets */}
               <CodeTabs
                 className="openapi-tabs__code-container-inner"
                 action={{