docusaurus-theme-openapi-docs 1.1.2 → 1.1.5

package/lib/theme/MimeTabs/index.js

@@ -0,0 +1,260 @@
+/* ============================================================================
+ * 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, {
+  Children,
+  cloneElement,
+  isValidElement,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+import { duplicates } from "@docusaurus/theme-common";
+import useIsBrowser from "@docusaurus/useIsBrowser";
+import clsx from "clsx";
+
+import styles from "./styles.module.css"; // A very rough duck type, but good enough to guard against mistakes while
+
+const {
+  useScrollPositionBlocker,
+  useTabGroupChoice,
+} = require("@docusaurus/theme-common/internal");
+
+// allowing customization
+
+function isTabItem(comp) {
+  return typeof comp.props.value !== "undefined";
+}
+
+function MimeTabsComponent(props) {
+  const {
+    lazy,
+    block,
+    defaultValue: defaultValueProp,
+    values: valuesProp,
+    groupId,
+    className,
+  } = props;
+  const children = Children.map(props.children, (child) => {
+    if (isValidElement(child) && isTabItem(child)) {
+      return child;
+    } // child.type.name will give non-sensical values in prod because of
+    // minification, but we assume it won't throw in prod.
+
+    throw new Error(
+      `Docusaurus error: Bad <Tabs> child <${
+        // @ts-expect-error: guarding against unexpected cases
+        typeof child.type === "string" ? child.type : child.type.name
+      }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`
+    );
+  });
+  const values =
+    valuesProp ?? // We only pick keys that we recognize. MDX would inject some keys by default
+    children.map(({ props: { value, label, attributes } }) => ({
+      value,
+      label,
+      attributes,
+    }));
+  const dup = duplicates(values, (a, b) => a.value === b.value);
+
+  if (dup.length > 0) {
+    throw new Error(
+      `Docusaurus error: Duplicate values "${dup
+        .map((a) => a.value)
+        .join(", ")}" found in <Tabs>. Every value needs to be unique.`
+    );
+  } // When defaultValueProp is null, don't show a default tab
+
+  const defaultValue =
+    defaultValueProp === null
+      ? defaultValueProp
+      : defaultValueProp ??
+        children.find((child) => child.props.default)?.props.value ??
+        children[0]?.props.value;
+
+  if (defaultValue !== null && !values.some((a) => a.value === defaultValue)) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${values
+        .map((a) => a.value)
+        .join(
+          ", "
+        )}. If you intend to show no default tab, use defaultValue={null} instead.`
+    );
+  }
+
+  const { tabGroupChoices, setTabGroupChoices } = useTabGroupChoice();
+  const [selectedValue, setSelectedValue] = useState(defaultValue);
+  const tabRefs = [];
+  const { blockElementScrollPositionUntilNextRender } =
+    useScrollPositionBlocker();
+
+  if (groupId != null) {
+    const relevantTabGroupChoice = tabGroupChoices[groupId];
+
+    if (
+      relevantTabGroupChoice != null &&
+      relevantTabGroupChoice !== selectedValue &&
+      values.some((value) => value.value === relevantTabGroupChoice)
+    ) {
+      setSelectedValue(relevantTabGroupChoice);
+    }
+  }
+
+  const handleTabChange = (event) => {
+    const newTab = event.currentTarget;
+    const newTabIndex = tabRefs.indexOf(newTab);
+    const newTabValue = values[newTabIndex].value;
+
+    if (newTabValue !== selectedValue) {
+      blockElementScrollPositionUntilNextRender(newTab);
+      setSelectedValue(newTabValue);
+
+      if (groupId != null) {
+        setTabGroupChoices(groupId, newTabValue);
+      }
+    }
+  };
+
+  const handleKeydown = (event) => {
+    let focusElement = null;
+
+    switch (event.key) {
+      case "ArrowRight": {
+        const nextTab = tabRefs.indexOf(event.currentTarget) + 1;
+        focusElement = tabRefs[nextTab] || tabRefs[0];
+        break;
+      }
+
+      case "ArrowLeft": {
+        const prevTab = tabRefs.indexOf(event.currentTarget) - 1;
+        focusElement = tabRefs[prevTab] || tabRefs[tabRefs.length - 1];
+        break;
+      }
+
+      default:
+        break;
+    }
+
+    focusElement?.focus();
+  };
+
+  const tabItemListContainerRef = useRef(null);
+  const [showTabArrows, setShowTabArrows] = useState(false);
+
+  useEffect(() => {
+    const tabOffsetWidth = tabItemListContainerRef.current.offsetWidth;
+    const tabScrollWidth = tabItemListContainerRef.current.scrollWidth;
+
+    if (tabOffsetWidth < tabScrollWidth) {
+      setShowTabArrows(true);
+    }
+  }, []);
+
+  const handleRightClick = () => {
+    tabItemListContainerRef.current.scrollLeft += 90;
+  };
+
+  const handleLeftClick = () => {
+    tabItemListContainerRef.current.scrollLeft -= 90;
+  };
+
+  return (
+    <div className="tabs__container">
+      <div className={styles.mimeTabsTopSection}>
+        {/* <strong>MIME Type</strong> */}
+        <div className={styles.mimeTabsContainer}>
+          {showTabArrows && (
+            <button
+              className={clsx(styles.tabArrow, styles.tabArrowLeft)}
+              onClick={handleLeftClick}
+            />
+          )}
+          <ul
+            ref={tabItemListContainerRef}
+            role="tablist"
+            aria-orientation="horizontal"
+            className={clsx(
+              styles.mimeTabsListContainer,
+              "tabs",
+              {
+                "tabs--block": block,
+              },
+              className
+            )}
+          >
+            {values.map(({ value, label, attributes }) => {
+              return (
+                <li
+                  role="tab"
+                  tabIndex={selectedValue === value ? 0 : -1}
+                  aria-selected={selectedValue === value}
+                  key={value}
+                  ref={(tabControl) => tabRefs.push(tabControl)}
+                  onKeyDown={handleKeydown}
+                  onFocus={handleTabChange}
+                  onClick={handleTabChange}
+                  {...attributes}
+                  className={clsx(
+                    "tabs__item",
+                    styles.tabItem,
+                    attributes?.className,
+                    {
+                      [styles.mimeTabActive]: selectedValue === value,
+                    }
+                  )}
+                >
+                  {/* <div
+                    className={clsx(styles.mimeTabDot, mimeTabDotStyle)}
+                  /> */}
+                  {label ?? value}
+                </li>
+              );
+            })}
+          </ul>
+          {showTabArrows && (
+            <button
+              className={clsx(styles.tabArrow, styles.tabArrowRight)}
+              onClick={handleRightClick}
+            />
+          )}
+        </div>
+      </div>
+      {/* <hr /> */}
+      {lazy ? (
+        cloneElement(
+          children.filter(
+            (tabItem) => tabItem.props.value === selectedValue
+          )[0],
+          {
+            className: clsx("margin-vert--md", styles.mimeSchemaContainer),
+          }
+        )
+      ) : (
+        <div className={clsx("margin-vert--md", styles.mimeSchemaContainer)}>
+          {children.map((tabItem, i) =>
+            cloneElement(tabItem, {
+              key: i,
+              hidden: tabItem.props.value !== selectedValue,
+            })
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function MimeTabs(props) {
+  const isBrowser = useIsBrowser();
+  return (
+    <MimeTabsComponent // Remount tabs after hydration
+      // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
+      key={String(isBrowser)}
+      {...props}
+    />
+  );
+}

package/lib/theme/MimeTabs/styles.module.css

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.tabItem {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 2rem;
+  margin-top: 0 !important;
+  margin-right: 0.5rem;
+  /* border: 1px solid var(--openapi-code-dim-dark);
+  border-radius: 0; */
+  font-weight: var(--ifm-font-weight-normal);
+  /* color: var(--openapi-code-dim-dark); */
+  font-size: 12px;
+}
+
+.tabItem:active {
+  background-color: var(--ifm-color-emphasis-100);
+}
+
+/* .tabItem:hover {
+  color: var(--ifm-color-emphasis-500) !important;
+} */
+
+.tabItem:last-child {
+  margin-right: 0 !important;
+}
+
+/* Open API Response Code Tabs */
+.mimeTabsTopSection {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.mimeTabsContainer {
+  display: flex;
+  align-items: center;
+  max-width: 390px;
+  /* padding-left: 1rem; */
+  overflow: hidden;
+}
+
+.mimeTabsListContainer {
+  overflow-y: hidden;
+  overflow-x: scroll;
+  scroll-behavior: smooth;
+}
+
+.mimeTabsListContainer::-webkit-scrollbar {
+  display: none;
+}
+
+/* Response Code Tabs - Colored Dots */
+.mimeTabDot {
+  width: 12.5px;
+  height: 12.5px;
+  margin-right: 5px;
+  border-radius: 50%;
+}
+
+.mimeTabDotSuccess {
+  background-color: var(--ifm-color-success);
+}
+
+.mimeTabDotDanger {
+  background-color: var(--ifm-color-danger);
+}
+
+.mimeTabDotInfo {
+  background-color: var(--ifm-color-info);
+}
+
+.mimeTabActive {
+  border-bottom-color: var(--ifm-tabs-color-active-border);
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+  color: var(--ifm-tabs-color-active);
+  background-color: var(--ifm-color-emphasis-100);
+}
+
+.mimeSchemaContainer {
+  max-width: 600px;
+}
+
+/* Tab Arrows */
+.tabArrow {
+  content: "";
+  height: 1.25rem;
+  width: 1.25rem;
+  border: none;
+  min-width: 1.25rem;
+  background: var(--ifm-menu-link-sublist-icon) 50% / 2rem 2rem;
+  filter: var(--ifm-menu-link-sublist-icon-filter);
+}
+
+.tabArrow:hover {
+  cursor: pointer;
+}
+
+.tabArrowLeft {
+  transform: rotate(270deg);
+}
+
+.tabArrowRight {
+  transform: rotate(90deg);
+}
+
+@media screen and (max-width: 500px) {
+  .mimeTabsTopSection {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  .mimeTabsContainer {
+    width: 100%;
+    margin-top: var(--ifm-spacing-vertical);
+    padding: 0;
+  }
+}

package/lib/theme/ParamsItem/index.js

@@ -37,6 +37,15 @@ function ParamsItem({
     </div>
   ));
 
+  const renderDefaultValue = guard(
+    schema.items ? schema.items.default : schema.default,
+    (value) => (
+      <div>
+        <ReactMarkdown children={`**Default value:** \`${value}\``} />
+      </div>
+    )
+  );
+
   const renderExample = guard(example, (example) => (
     <div>{`Example: ${example}`}</div>
   ));
@@ -58,6 +67,7 @@ function ParamsItem({
       {renderSchemaName}
       {renderSchemaRequired}
       {renderSchema}
+      {renderDefaultValue}
       {renderDescription}
       {renderExample}
       {renderExamples}

package/lib/theme/ResponseSamples/index.js

@@ -0,0 +1,27 @@
+/* ============================================================================
+ * 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 CodeBlock from "@theme/CodeBlock";
+
+import styles from "./styles.module.css";
+
+function ResponseSamples({ responseExample }) {
+  return (
+    <div className={styles.responseSamplesContainer}>
+      <CodeBlock
+        language="javascript"
+        className={styles.responseSamplesCodeBlock}
+      >
+        {responseExample}
+      </CodeBlock>
+    </div>
+  );
+}
+
+export default ResponseSamples;

package/lib/theme/ResponseSamples/styles.module.css

@@ -0,0 +1,7 @@
+.responseSamplesContainer {
+  margin-top: 2rem;
+}
+
+.responseSamplesTabItem {
+  width: 100%;
+}

package/lib/theme/SchemaItem/index.js

@@ -21,10 +21,12 @@ function SchemaItem({
   required,
   schemaDescription,
   schemaName,
+  defaultValue,
 }) {
-  const renderRequired = guard(required, () => (
-    <strong className={styles.required}> required</strong>
-  ));
+  const renderRequired = guard(
+    Array.isArray(required) ? required.includes(name) : required,
+    () => <strong className={styles.required}> required</strong>
+  );
 
   const renderSchemaDescription = guard(schemaDescription, (description) => (
     <div className={styles.schemaDescription}>
@@ -38,12 +40,22 @@ function SchemaItem({
     </div>
   ));
 
+  const renderDefaultValue = guard(
+    typeof defaultValue === "boolean" ? defaultValue.toString() : defaultValue,
+    (value) => (
+      <div className={styles.schemaQualifierMessage}>
+        <ReactMarkdown children={`**Default value:** \`${value}\``} />
+      </div>
+    )
+  );
+
   const schemaContent = (
     <div>
       <strong>{name}</strong>
       <span className={styles.schemaName}> {schemaName}</span>
       {renderRequired}
       {renderQualifierMessage}
+      {renderDefaultValue}
       {renderSchemaDescription}
     </div>
   );

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

@@ -38,14 +38,6 @@
   display: none;
 }
 
-.schemaTabsContainer {
-  display: flex;
-  align-items: center;
-  max-width: 390px;
-  padding-left: 3px;
-  overflow: hidden;
-}
-
 .schemaTabsListContainer {
   padding: 0 0.25rem;
   overflow-y: hidden;

package/lib-next/markdown/schema.js

@@ -5,22 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 function prettyName(schema, circular) {
-  if (schema.$ref) {
-    return schema.$ref.replace("#/components/schemas/", "") + circular
-      ? " (circular)"
-      : "";
-  }
-
   if (schema.format) {
     return schema.format;
   }
 
   if (schema.allOf) {
+    if (typeof schema.allOf[0] === "string") {
+      // @ts-ignore
+      if (schema.allOf[0].includes("circular")) {
+        return schema.allOf[0];
+      }
+    }
+
+    return "object";
+  }
+
+  if (schema.oneOf) {
+    return "object";
+  }
+
+  if (schema.anyOf) {
     return "object";
   }
 
   if (schema.type === "object") {
-    return schema.xml?.name ?? schema.type;
+    return schema.xml?.name ?? schema.type; // return schema.type;
+  }
+
+  if (schema.type === "array") {
+    return schema.xml?.name ?? schema.type; // return schema.type;
   }
 
   return schema.title ?? schema.type;
@@ -35,8 +48,6 @@ export function getSchemaName(schema, circular) {
 }
 export function getQualifierMessage(schema) {
   // TODO:
-  // - maxItems
-  // - minItems
   // - uniqueItems
   // - maxProperties
   // - minProperties
@@ -45,24 +56,52 @@ export function getQualifierMessage(schema) {
     return undefined;
   }
 
-  if (schema.items) {
+  if (
+    schema.items &&
+    schema.minItems === undefined &&
+    schema.maxItems === undefined
+  ) {
     return getQualifierMessage(schema.items);
   }
 
   let message = "**Possible values:** ";
   let qualifierGroups = [];
 
+  if (schema.items && schema.items.enum) {
+    if (schema.items.enum) {
+      qualifierGroups.push(
+        `[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`
+      );
+    }
+  }
+
   if (schema.minLength || schema.maxLength) {
     let lengthQualifier = "";
+    let minLength;
+    let maxLength;
 
-    if (schema.minLength) {
-      lengthQualifier += `${schema.minLength} ≤ `;
+    if (schema.minLength && schema.minLength > 1) {
+      minLength = `\`>= ${schema.minLength} characters\``;
     }
 
-    lengthQualifier += "length";
+    if (schema.minLength && schema.minLength === 1) {
+      minLength = `\`non-empty\``;
+    }
 
     if (schema.maxLength) {
-      lengthQualifier += ` ≤ ${schema.maxLength}`;
+      maxLength = `\`<= ${schema.maxLength} characters\``;
+    }
+
+    if (minLength && !maxLength) {
+      lengthQualifier += minLength;
+    }
+
+    if (maxLength && !minLength) {
+      lengthQualifier += maxLength;
+    }
+
+    if (minLength && maxLength) {
+      lengthQualifier += `${minLength} and ${maxLength}`;
     }
 
     qualifierGroups.push(lengthQualifier);
@@ -75,23 +114,35 @@ export function getQualifierMessage(schema) {
     typeof schema.exclusiveMaximum === "number"
   ) {
     let minmaxQualifier = "";
+    let minimum;
+    let maximum;
 
     if (typeof schema.exclusiveMinimum === "number") {
-      minmaxQualifier += `${schema.exclusiveMinimum} < `;
+      minimum = `\`> ${schema.exclusiveMinimum}\``;
     } else if (schema.minimum && !schema.exclusiveMinimum) {
-      minmaxQualifier += `${schema.minimum} ≤ `;
+      minimum = `\`>= ${schema.minimum}\``;
     } else if (schema.minimum && schema.exclusiveMinimum === true) {
-      minmaxQualifier += `${schema.minimum} < `;
+      minimum = `\`> ${schema.minimum}\``;
     }
 
-    minmaxQualifier += "value";
-
     if (typeof schema.exclusiveMaximum === "number") {
-      minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+      maximum = `\`< ${schema.exclusiveMaximum}\``;
     } else if (schema.maximum && !schema.exclusiveMaximum) {
-      minmaxQualifier += ` ≤ ${schema.maximum}`;
+      maximum = `\`<= ${schema.maximum}\``;
     } else if (schema.maximum && schema.exclusiveMaximum === true) {
-      minmaxQualifier += ` < ${schema.maximum}`;
+      maximum = `\`< ${schema.maximum}\``;
+    }
+
+    if (minimum && !maximum) {
+      minmaxQualifier += minimum;
+    }
+
+    if (maximum && !minimum) {
+      minmaxQualifier += maximum;
+    }
+
+    if (minimum && maximum) {
+      minmaxQualifier += `${minimum} and ${maximum}`;
     }
 
     qualifierGroups.push(minmaxQualifier);
@@ -101,12 +152,27 @@ export function getQualifierMessage(schema) {
     qualifierGroups.push(
       `Value must match regular expression \`${schema.pattern}\``
     );
+  } // Check if discriminator mapping
+
+  const discriminator = schema;
+
+  if (discriminator.mapping) {
+    const values = Object.keys(discriminator.mapping);
+    qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
   if (schema.enum) {
     qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
+  if (schema.minItems) {
+    qualifierGroups.push(`\`>= ${schema.minItems}\``);
+  }
+
+  if (schema.maxItems) {
+    qualifierGroups.push(`\`<= ${schema.maxItems}\``);
+  }
+
   if (qualifierGroups.length === 0) {
     return undefined;
   }

package/lib-next/theme/ApiDemoPanel/Body/index.js

@@ -178,7 +178,7 @@ function Body({ requestBodyMetadata, jsonRequestBodyExample }) {
   let language = "plaintext";
   let exampleBodyString = ""; //"body content";
 
-  if (contentType === "application/json") {
+  if (contentType === "application/json" || contentType.endsWith("+json")) {
     if (jsonRequestBodyExample) {
       exampleBodyString = JSON.stringify(jsonRequestBodyExample, null, 2);
     }