docusaurus-theme-openapi-docs 1.5.1 → 1.6.0

package/lib-next/theme/ParamsItem/index.js

@@ -8,6 +8,8 @@
 import React from "react";
 
 import CodeBlock from "@theme/CodeBlock";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
 /* eslint-disable import/no-extraneous-dependencies*/
 import { createDescription } from "docusaurus-theme-openapi-docs/lib/markdown/createDescription";
 /* eslint-disable import/no-extraneous-dependencies*/
@@ -16,7 +18,10 @@ import {
   getSchemaName,
 } from "docusaurus-theme-openapi-docs/lib/markdown/schema";
 /* eslint-disable import/no-extraneous-dependencies*/
-import { guard } from "docusaurus-theme-openapi-docs/lib/markdown/utils";
+import {
+  guard,
+  toString,
+} from "docusaurus-theme-openapi-docs/lib/markdown/utils";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
 
@@ -25,6 +30,10 @@ import styles from "./styles.module.css";
 function ParamsItem({
   param: { description, example, examples, name, required, schema },
 }) {
+  if (!schema || !schema?.type) {
+    schema = { type: "any" };
+  }
+
   const renderSchemaName = guard(schema, (schema) => (
     <span className={styles.schemaName}> {getSchemaName(schema)}</span>
   ));
@@ -76,17 +85,35 @@ function ParamsItem({
     )
   );
 
-  const renderExample = guard(example, (example) => (
-    <div>{`Example: ${example}`}</div>
+  const renderExample = guard(toString(example), (example) => (
+    <div>
+      <strong>Example: </strong>
+      {example}
+    </div>
   ));
 
   const renderExamples = guard(examples, (examples) => {
     const exampleEntries = Object.entries(examples);
     return (
       <>
-        {exampleEntries.map(([k, v]) => (
-          <div>{`Example (${k}): ${v.value}`}</div>
-        ))}
+        <strong>Examples:</strong>
+        <SchemaTabs>
+          {exampleEntries.map(([exampleName, exampleProperties]) => (
+            <TabItem value={exampleName} label={exampleName}>
+              {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
+              {exampleProperties.description && (
+                <p>
+                  <strong>Description: </strong>
+                  <span>{exampleProperties.description}</span>
+                </p>
+              )}
+              <p>
+                <strong>Example: </strong>
+                <code>{exampleProperties.value}</code>
+              </p>
+            </TabItem>
+          ))}
+        </SchemaTabs>
       </>
     );
   });

package/lib-next/theme/SchemaItem/index.js

@@ -11,7 +11,10 @@ import CodeBlock from "@theme/CodeBlock";
 /* eslint-disable import/no-extraneous-dependencies*/
 import { createDescription } from "docusaurus-theme-openapi-docs/lib/markdown/createDescription";
 /* eslint-disable import/no-extraneous-dependencies*/
-import { guard } from "docusaurus-theme-openapi-docs/lib/markdown/utils";
+import {
+  guard,
+  toString,
+} from "docusaurus-theme-openapi-docs/lib/markdown/utils";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
 
@@ -23,11 +26,20 @@ function SchemaItem({
   name,
   qualifierMessage,
   required,
-  deprecated,
-  schemaDescription,
   schemaName,
-  defaultValue,
+  schema,
 }) {
+  let deprecated;
+  let schemaDescription;
+  let defaultValue;
+  let nullable;
+  if (schema) {
+    deprecated = schema.deprecated;
+    schemaDescription = schema.description;
+    defaultValue = schema.default;
+    nullable = schema.nullable;
+  }
+
   const renderRequired = guard(
     Array.isArray(required) ? required.includes(name) : required,
     () => <strong className={styles.required}> required</strong>
@@ -37,6 +49,10 @@ function SchemaItem({
     <strong className={styles.deprecated}> deprecated</strong>
   ));
 
+  const renderNullable = guard(nullable, () => (
+    <strong className={styles.nullable}> nullable</strong>
+  ));
+
   const renderSchemaDescription = guard(schemaDescription, (description) => (
     <div>
       <ReactMarkdown
@@ -67,19 +83,17 @@ function SchemaItem({
     </div>
   ));
 
-  const renderDefaultValue = guard(
-    typeof defaultValue === "boolean" ? defaultValue.toString() : defaultValue,
-    (value) => (
-      <div className={styles.schemaQualifierMessage}>
-        <ReactMarkdown children={`**Default value:** \`${value}\``} />
-      </div>
-    )
-  );
+  const renderDefaultValue = guard(toString(defaultValue), (value) => (
+    <div className={styles.schemaQualifierMessage}>
+      <ReactMarkdown children={`**Default value:** \`${value}\``} />
+    </div>
+  ));
 
   const schemaContent = (
     <div>
       <strong className={deprecated && styles.strikethrough}>{name}</strong>
       <span className={styles.schemaName}> {schemaName}</span>
+      {renderNullable}
       {!deprecated && renderRequired}
       {renderDeprecated}
       {renderQualifierMessage}

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

@@ -28,6 +28,11 @@
   color: var(--openapi-deprecated);
 }
 
+.nullable {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-nullable);
+}
+
 .strikethrough {
   text-decoration: line-through;
 }

package/lib-next/theme/SchemaTabs/index.js

@@ -241,11 +241,11 @@ function SchemaTabsComponent(props) {
               (tabItem) => tabItem.props.value === defaultValue
             )[0],
           {
-            className: "margin-vert--md",
+            className: styles.marginVertical,
           }
         )
       ) : (
-        <div className="margin-vert--md">
+        <div className={styles.marginVertical}>
           {children.map((tabItem, i) =>
             cloneElement(tabItem, {
               key: i,

package/lib-next/theme/SchemaTabs/styles.module.css

@@ -103,3 +103,8 @@
     width: 100%;
   }
 }
+
+.marginVertical {
+  margin-top: 1rem !important;
+  margin-bottom: unset !important;
+}

package/lib-next/theme/styles.css

@@ -8,6 +8,7 @@
 :root {
   --openapi-required: var(--ifm-color-danger);
   --openapi-deprecated: var(--ifm-color-warning);
+  --openapi-nullable: var(--ifm-color-info);
   --openapi-code-blue: var(--ifm-color-info);
   --openapi-code-red: var(--ifm-color-danger);
   --openapi-code-orange: var(--ifm-color-warning);
@@ -77,10 +78,14 @@
 
 .theme-api-markdown details li {
   list-style: none;
-  padding-bottom: 5px;
   padding-top: 5px;
 }
 
+.theme-api-markdown .tabs__item {
+  padding-bottom: unset;
+  padding-top: unset;
+}
+
 .theme-api-markdown details > div > div {
   padding-top: unset !important;
   border-top: unset !important;
@@ -244,6 +249,8 @@
   color: var(--ifm-color-success);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--python.tabs__item--active {
@@ -268,6 +275,8 @@
   color: var(--ifm-color-info);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--go.tabs__item--active {
@@ -292,6 +301,8 @@
   color: var(--ifm-color-warning);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--javascript.tabs__item--active {
@@ -316,6 +327,8 @@
   color: var(--ifm-color-danger);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--bash.tabs__item--active {
@@ -340,6 +353,8 @@
   color: var(--ifm-color-danger);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--ruby.tabs__item--active {
@@ -364,6 +379,8 @@
   color: var(--ifm-color-gray-500);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--csharp.tabs__item--active {
@@ -388,6 +405,8 @@
   color: var(--ifm-color-success);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--nodejs.tabs__item--active {
@@ -412,6 +431,8 @@
   color: var(--ifm-color-gray-500);
   padding-left: 1.4rem;
   padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
 }
 
 .code__tab--php.tabs__item--active {
@@ -424,7 +445,41 @@
   overflow: auto;
 }
 
+.code__tab--java::after {
+  content: "";
+  width: 28px;
+  height: 28px;
+  background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/java/java-original.svg");
+  margin-block: auto;
+}
+
+.code__tab--java {
+  color: var(--ifm-color-warning);
+  padding-left: 1.4rem;
+  padding-right: 1.4rem;
+  padding-top: 1rem !important;
+  padding-bottom: 1rem !important;
+}
+
+.code__tab--java.tabs__item--active {
+  border-bottom-color: var(--ifm-color-warning);
+  background-color: var(--ifm-color-emphasis-100);
+}
+
+.language-java {
+  max-height: 500px;
+  overflow: auto;
+}
+
 /* Prism code styles */
-.prism-code.language-json {
+.prism-code.language-java {
   white-space: pre !important;
 }
+
+.openapi__logo {
+  width: 250px;
+}
+
+div:has(> ul.openapi-tabs__security-schemes) {
+  max-width: 100%;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -31,8 +31,8 @@
     "format:lib-next": "prettier --config ../../.prettierrc.json --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.0.1",
-    "@docusaurus/types": "^2.0.1",
+    "@docusaurus/module-type-aliases": ">=2.0.1 <2.3.0",
+    "@docusaurus/types": ">=2.0.1 <2.3.0",
     "@types/concurrently": "^6.3.0",
     "@types/crypto-js": "^4.1.0",
     "@types/file-saver": "^2.0.5",
@@ -43,18 +43,19 @@
     "concurrently": "^5.2.0"
   },
   "dependencies": {
-    "@docusaurus/theme-common": "^2.0.1",
+    "@docusaurus/theme-common": ">=2.0.1 <2.3.0",
     "@mdx-js/react": "^1.6.21",
-    "@paloaltonetworks/postman-code-generators": "^1.1.12",
+    "@paloaltonetworks/postman-code-generators": "^1.1.15",
     "@paloaltonetworks/postman-collection": "^4.1.0",
     "@reduxjs/toolkit": "^1.7.1",
     "buffer": "^6.0.3",
     "clsx": "^1.1.1",
     "crypto-js": "^4.1.1",
-    "docusaurus-plugin-openapi-docs": "^1.5.1",
+    "docusaurus-plugin-openapi-docs": "^1.6.0",
     "file-saver": "^2.0.5",
     "immer": "^9.0.7",
     "lodash": "^4.17.20",
+    "node-polyfill-webpack-plugin": "^2.0.1",
     "process": "^0.11.10",
     "react-live": "^3.1.1",
     "react-magic-dropzone": "^1.0.1",
@@ -73,5 +74,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "11d2c2fdb2bc81048097b05bc65698777d54e456"
+  "gitHead": "937e6543af8c1575877a0ebe7c5732e5cffaa37d"
 }

package/src/index.ts

@@ -8,7 +8,8 @@
 import path from "path";
 
 import type { Plugin } from "@docusaurus/types";
-import { ProvidePlugin } from "webpack";
+
+const NodePolyfillPlugin = require("node-polyfill-webpack-plugin");
 
 export default function docusaurusThemeOpenAPI(): Plugin<void> {
   return {
@@ -29,18 +30,7 @@ export default function docusaurusThemeOpenAPI(): Plugin<void> {
 
     configureWebpack() {
       return {
-        plugins: [
-          new ProvidePlugin({
-            Buffer: [require.resolve("buffer/"), "Buffer"],
-            process: require.resolve("process/browser"),
-          }),
-        ],
-        resolve: {
-          fallback: {
-            buffer: require.resolve("buffer/"),
-            process: require.resolve("process/browser"),
-          },
-        },
+        plugins: [new NodePolyfillPlugin()],
       };
     },
   };

package/src/markdown/utils.ts

@@ -24,7 +24,7 @@ export function guard<T>(
   value: T | undefined | string,
   cb: (value: T) => Children
 ): string {
-  if (value) {
+  if (value !== undefined) {
     const children = cb(value as T);
     return render(children);
   }
@@ -37,3 +37,20 @@ export function render(children: Children): string {
   }
   return children ?? "";
 }
+
+export function toString(value: any): string | undefined {
+  // Return as-is if already string
+  if (typeof value === "string") {
+    return value;
+  }
+  // Return undefined if null or undefined
+  if (value == null) {
+    return undefined;
+  }
+  // Return formatted array if Array
+  if (Array.isArray(value)) {
+    return `[${value.join(", ")}]`;
+  }
+  // Coerce to string in all other cases,
+  return value + "";
+}

package/src/theme/ApiDemoPanel/Curl/index.tsx

@@ -15,6 +15,7 @@ import CodeTabs from "@theme/ApiDemoPanel/CodeTabs";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
 import CodeBlock from "@theme/CodeBlock";
 import clsx from "clsx";
+import merge from "lodash/merge";
 
 import styles from "./styles.module.css";
 
@@ -100,6 +101,16 @@ export const languageSet: Language[] = [
     },
     variant: "cURL",
   },
+  {
+    highlight: "java",
+    language: "java",
+    logoClass: "java",
+    options: {
+      followRedirect: true,
+      trimRequestBody: true,
+    },
+    variant: "OkHttp",
+  },
 ];
 
 export interface Props {
@@ -136,23 +147,37 @@ function Curl({ postman, codeSamples }: Props) {
 
   const auth = useTypedSelector((state: any) => state.auth);
 
-  // TODO
+  // User-defined languages array
+  // Can override languageSet, change order of langs, override options and variants
   const langs = [
     ...((siteConfig?.themeConfig?.languageTabs as Language[] | undefined) ??
       languageSet),
     ...codeSamples,
   ];
 
-  const defaultLang: Language[] = languageSet.filter(
+  // Filter languageSet by user-defined langs
+  const filteredLanguageSet = languageSet.filter((ls) => {
+    return langs.some((lang) => {
+      return lang.language === ls.language;
+    });
+  });
+
+  // Merge user-defined langs into languageSet
+  const mergedLangs = merge(filteredLanguageSet, langs);
+
+  // Read defaultLang from localStorage
+  const defaultLang: Language[] = mergedLangs.filter(
     (lang) =>
       lang.language === localStorage.getItem("docusaurus.tab.code-samples")
   );
 
   const [language, setLanguage] = useState(() => {
-    if (langs.length === 1) {
-      return langs[0];
+    // Return first index if only 1 user-defined language exists
+    if (mergedLangs.length === 1) {
+      return mergedLangs[0];
     }
-    return defaultLang[0] ?? langs[0];
+    // Fall back to language in localStorage or first user-defined language
+    return defaultLang[0] ?? mergedLangs[0];
   });
 
   const [codeText, setCodeText] = useState("");
@@ -186,7 +211,7 @@ function Curl({ postman, codeSamples }: Props) {
     } else if (language && !!language.source) {
       setCodeText(language.source);
     } else if (language && !language.options) {
-      const langSource = languageSet.filter(
+      const langSource = mergedLangs.filter(
         (lang) => lang.language === language.language
       );
 
@@ -233,6 +258,7 @@ function Curl({ postman, codeSamples }: Props) {
     queryParams,
     server,
     auth,
+    mergedLangs,
   ]);
 
   if (language === undefined) {
@@ -242,7 +268,7 @@ function Curl({ postman, codeSamples }: Props) {
   return (
     <>
       <CodeTabs groupId="code-samples" action={setLanguage}>
-        {langs.map((lang) => {
+        {mergedLangs.map((lang) => {
           return (
             <CodeTab
               value={lang.language}
@@ -254,7 +280,9 @@ function Curl({ postman, codeSamples }: Props) {
               }
               attributes={{ className: `code__tab--${lang.logoClass}` }}
             >
-              <CodeBlock language={lang.highlight}>{codeText}</CodeBlock>
+              <CodeBlock language={lang.highlight} className={styles.codeBlock}>
+                {codeText}
+              </CodeBlock>
             </CodeTab>
           );
         })}

package/src/theme/ApiDemoPanel/Curl/styles.module.css

@@ -82,3 +82,8 @@
   background: var(--ifm-menu-color-background-active);
   color: var(--ifm-menu-color-active);
 }
+
+.codeBlock code {
+  max-width: revert;
+  max-height: revert;
+}

package/src/theme/ApiDemoPanel/Request/index.tsx

@@ -25,7 +25,7 @@ function Request({ item }: { item: NonNullable<ApiItem> }) {
   const response = useTypedSelector((state: any) => state.response.value);
   const postman = new sdk.Request(item.postman);
   const metadata = useDoc();
-  const { proxy } = metadata.frontMatter;
+  const { proxy, hide_send_button } = metadata.frontMatter;
 
   const params = {
     path: [] as ParameterObject[],
@@ -48,7 +48,9 @@ function Request({ item }: { item: NonNullable<ApiItem> }) {
         <summary>
           <div className={`details__request-summary`}>
             <h4>Request</h4>
-            {item.servers && <Execute postman={postman} proxy={proxy} />}
+            {item.servers && !hide_send_button && (
+              <Execute postman={postman} proxy={proxy} />
+            )}
           </div>
         </summary>
         <div className={styles.optionsPanel}>