docusaurus-theme-openapi-docs 4.0.0 → 4.1.0

package/lib/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/lib/theme/ApiItem/index.js

@@ -25,7 +25,7 @@ const useDocusaurusContext_1 = __importDefault(
 const useIsBrowser_1 = __importDefault(require("@docusaurus/useIsBrowser"));
 const slice_1 = require("@theme/ApiExplorer/Authorization/slice");
 const persistanceMiddleware_1 = require("@theme/ApiExplorer/persistanceMiddleware");
-const Layout_1 = __importDefault(require("@theme/DocItem/Layout"));
+const Layout_1 = __importDefault(require("@theme/ApiItem/Layout"));
 const Metadata_1 = __importDefault(require("@theme/DocItem/Metadata"));
 const clsx_1 = __importDefault(require("clsx"));
 const react_redux_1 = require("react-redux");

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

@@ -17,7 +17,8 @@ export interface Props {
         required: boolean;
         deprecated: boolean;
         schema: any;
+        enumDescriptions?: [string, string][];
     };
 }
-declare function ParamsItem({ param: { description, example, examples, name, required, schema, deprecated }, }: Props): React.JSX.Element;
+declare function ParamsItem({ param, ...rest }: Props): React.JSX.Element;
 export default ParamsItem;

package/lib/theme/ParamsItem/index.js

@@ -19,15 +19,45 @@ const TabItem_1 = __importDefault(require("@theme/TabItem"));
 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 schema_1 = require("../../markdown/schema");
 const utils_1 = require("../../markdown/utils");
-function ParamsItem({
-  param: { description, example, examples, name, required, schema, deprecated },
-}) {
+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 ParamsItem({ param, ...rest }) {
+  const {
+    description,
+    example,
+    examples,
+    name,
+    required,
+    deprecated,
+    enumDescriptions,
+  } = param;
+  let schema = param.schema;
+  let defaultValue;
   if (!schema || !schema?.type) {
     schema = { type: "any" };
   }
+  if (schema) {
+    if (schema.items) {
+      defaultValue = schema.items.default;
+    } else {
+      defaultValue = schema.default;
+    }
+  }
   const renderSchemaName = (0, utils_1.guard)(schema, (schema) =>
     react_1.default.createElement(
       "span",
@@ -91,21 +121,47 @@ function ParamsItem({
       })
     )
   );
-  const renderDefaultValue = (0, utils_1.guard)(
-    schema && schema.items
-      ? schema.items.default
-      : schema
-        ? schema.default
-        : undefined,
-    (value) =>
-      react_1.default.createElement(
+  const renderEnumDescriptions = (0, utils_1.guard)(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return react_1.default.createElement(react_markdown_1.default, {
+        rehypePlugins: [rehype_raw_1.default],
+        remarkPlugins: [remark_gfm_1.default],
+        children: 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(react_markdown_1.default, {
-          children: `**Default value:** \`${value}\``,
-        })
-      )
-  );
+        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;
+  }
   const renderExample = (0, utils_1.guard)(
     (0, utils_1.toString)(example),
     (example) =>
@@ -186,8 +242,9 @@ function ParamsItem({
       renderDeprecated
     ),
     renderSchema,
-    renderDefaultValue,
     renderDescription,
+    renderEnumDescriptions,
+    renderDefaultValue(),
     renderExample,
     renderExamples
   );

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

@@ -9,4 +9,4 @@ export interface Props {
     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,16 @@ function SchemaItem({
       "nullable"
     )
   );
+  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,
+      });
+    }
+  );
   const renderSchemaDescription = (0, utils_1.guard)(
     schemaDescription,
     (description) =>
@@ -103,15 +138,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 +225,11 @@ function SchemaItem({
       renderRequired,
       renderDeprecated
     ),
-    renderQualifierMessage,
-    renderDefaultValue,
     renderSchemaDescription,
+    renderEnumDescriptions,
+    renderQualifierMessage,
+    renderDefaultValue(),
+    renderExample(),
     collapsibleSchemaContent ?? collapsibleSchemaContent
   );
   return react_1.default.createElement(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "4.0.0",
+  "version": "4.1.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,13 @@
     "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",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.1.0",
     "crypto-js": "^4.1.1",
-    "docusaurus-plugin-openapi-docs": "^4.0.0",
+    "docusaurus-plugin-openapi-docs": "^4.1.0",
     "docusaurus-plugin-sass": "^0.2.3",
     "file-saver": "^2.0.5",
     "lodash": "^4.17.20",
@@ -57,6 +57,7 @@
     "react-modal": "^3.15.1",
     "react-redux": "^7.2.0",
     "rehype-raw": "^6.1.1",
+    "remark-gfm": "3.0.1",
     "sass": "^1.58.1",
     "sass-loader": "^13.3.2",
     "webpack": "^5.61.0",
@@ -69,5 +70,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "79d74177cfd54d2750dde1e15c6ea166f9ca4be9"
+  "gitHead": "4e771d309f6defe395449b26cc3c65814d72cbcc"
 }

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;
@@ -339,6 +229,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
 
   return (
     <>
+      {/* Outer language tabs */}
       <CodeTabs
         groupId="code-samples"
         action={{
@@ -347,6 +238,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
           setSelectedSample: setSelectedSample,
         }}
         languageSet={mergedLangs}
+        defaultValue={defaultLang[0]?.language ?? mergedLangs[0].language}
         lazy
       >
         {mergedLangs.map((lang) => {
@@ -359,6 +251,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 +293,7 @@ function CodeSnippets({ postman, codeSamples }: Props) {
                 </CodeTabs>
               )}
 
+              {/* Inner generated code snippets */}
               <CodeTabs
                 className="openapi-tabs__code-container-inner"
                 action={{

package/src/theme/ApiExplorer/CodeSnippets/languages.ts

@@ -6,9 +6,9 @@
  * ========================================================================== */
 
 import find from "lodash/find";
-import isArray from "lodash/isArray";
 import mergeWith from "lodash/mergeWith";
 import unionBy from "lodash/unionBy";
+import codegen from "postman-code-generators";
 
 import { CodeSample, Language } from "./code-snippets-types";
 
@@ -50,10 +50,7 @@ export const mergeArraysbyLanguage = (arr1: any, arr2: any) => {
       find(arr2, ["language", item["language"]]),
     ];
     return mergeWith({}, ...matchingItems, (objValue: any) => {
-      if (isArray(objValue)) {
-        return objValue;
-      }
-      return undefined;
+      return objValue;
     });
   });
 };
@@ -73,3 +70,27 @@ export function getCodeSampleSourceFromLanguage(language: Language) {
 
   return "";
 }
+
+export function generateLanguageSet() {
+  const languageSet: Language[] = [];
+  codegen.getLanguageList().forEach((language: any) => {
+    const variants: any = [];
+    language.variants.forEach((variant: any) => {
+      variants.push(variant.key);
+    });
+    languageSet.push({
+      highlight: language.syntax_mode,
+      language: language.key,
+      codeSampleLanguage: language.label,
+      logoClass: language.key,
+      options: {
+        longFormat: false,
+        followRedirect: true,
+        trimRequestBody: true,
+      },
+      variant: variants[0],
+      variants: variants,
+    });
+  });
+  return languageSet;
+}