docusaurus-theme-openapi-docs 4.0.1 → 4.2.0

package/src/theme/SchemaItem/index.tsx

@@ -11,39 +11,71 @@ import CodeBlock from "@theme/CodeBlock";
 import clsx from "clsx";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkGfm from "remark-gfm";
 
 import { createDescription } from "../../markdown/createDescription";
 import { guard } from "../../markdown/utils";
 
 export interface Props {
-  children: ReactNode;
-  collapsible: boolean;
-  name: string;
-  qualifierMessage: string | undefined;
-  required: boolean;
-  schemaName: string;
+  children?: ReactNode;
+  collapsible?: boolean;
+  name?: string;
+  qualifierMessage?: string | undefined;
+  required?: boolean;
+  schemaName?: string;
   // TODO should probably be typed
-  schema: any;
-  discriminator: boolean;
+  schema?: any;
+  discriminator?: boolean;
 }
 
-export default function SchemaItem({
-  children: collapsibleSchemaContent,
-  collapsible,
-  name,
-  qualifierMessage,
-  required,
-  schemaName,
-  schema,
-}: Props) {
+const transformEnumDescriptions = (
+  enumDescriptions?: Record<string, string>
+) => {
+  if (enumDescriptions) {
+    return Object.entries(enumDescriptions);
+  }
+
+  return [];
+};
+
+const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
+  if (enumDescriptions?.length) {
+    return `| Enum Value | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+
+  return "";
+};
+
+export default function SchemaItem(props: Props) {
+  const {
+    children: collapsibleSchemaContent,
+    collapsible,
+    name,
+    qualifierMessage,
+    required,
+    schemaName,
+    schema,
+  } = props;
   let deprecated;
   let schemaDescription;
-  let defaultValue;
+  let defaultValue: string | undefined;
+  let example: string | undefined;
   let nullable;
+  let enumDescriptions: [string, string][] = [];
+
   if (schema) {
     deprecated = schema.deprecated;
     schemaDescription = schema.description;
+    enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
+    example = schema.example;
     nullable = schema.nullable;
   }
 
@@ -60,6 +92,21 @@ export default function SchemaItem({
     <span className="openapi-schema__nullable">nullable</span>
   ));
 
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <div style={{ marginTop: ".5rem" }}>
+          <ReactMarkdown
+            remarkPlugins={[remarkGfm]}
+            rehypePlugins={[rehypeRaw]}
+            children={value}
+          />
+        </div>
+      );
+    }
+  );
+
   const renderSchemaDescription = guard(schemaDescription, (description) => (
     <div>
       <ReactMarkdown
@@ -90,11 +137,53 @@ export default function SchemaItem({
     </div>
   ));
 
-  const renderDefaultValue = guard(defaultValue, (value) => (
-    <div className="">
-      <ReactMarkdown children={`**Default value:** \`${value}\``} />
-    </div>
-  ));
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return (
+          <div>
+            <strong>Default value: </strong>
+            <span>
+              <code>{defaultValue}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Default value: </strong>
+          <span>
+            <code>{JSON.stringify(defaultValue)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
+  function renderExample() {
+    if (example !== undefined) {
+      if (typeof example === "string") {
+        return (
+          <div>
+            <strong>Example: </strong>
+            <span>
+              <code>{example}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Example: </strong>
+          <span>
+            <code>{JSON.stringify(example)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
 
   const schemaContent = (
     <div>
@@ -114,9 +203,11 @@ export default function SchemaItem({
         {renderRequired}
         {renderDeprecated}
       </span>
-      {renderQualifierMessage}
-      {renderDefaultValue}
       {renderSchemaDescription}
+      {renderEnumDescriptions}
+      {renderQualifierMessage}
+      {renderDefaultValue()}
+      {renderExample()}
       {collapsibleSchemaContent ?? collapsibleSchemaContent}
     </div>
   );

package/src/theme/SkeletonLoader/index.tsx

@@ -0,0 +1,18 @@
+/* ============================================================================
+ * 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";
+
+interface Props {
+  size?: "sm" | "md" | "lg";
+}
+
+const SkeletonLoader: React.FC<Props> = (props) => {
+  return <div className={`openapi-skeleton ${props.size ?? "md"}`}></div>;
+};
+
+export default SkeletonLoader;

package/src/theme/StatusCodes/index.tsx

@@ -0,0 +1,72 @@
+/* ============================================================================
+ * 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 ApiTabs from "@theme/ApiTabs";
+import Details from "@theme/Details";
+import { ResponseHeaders } from "@theme/ResponseExamples";
+import ResponseSchema from "@theme/ResponseSchema";
+import TabItem from "@theme/TabItem";
+import { createDescription } from "docusaurus-plugin-openapi-docs/lib/markdown/createDescription";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/lib/types";
+
+interface Props {
+  id?: string;
+  label?: string;
+  responses: ApiItem["responses"];
+}
+
+const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
+  if (!responses) return null;
+
+  const codes = Object.keys(responses);
+  if (codes.length === 0) return null;
+
+  return (
+    <ApiTabs label={label} id={id}>
+      {codes.map((code) => {
+        const response = responses[code];
+        const responseHeaders = response.headers;
+
+        return (
+          // @ts-ignore
+          <TabItem key={code} label={code} value={code}>
+            <div>
+              {response.description && (
+                <div style={{ marginTop: ".5rem", marginBottom: ".5rem" }}>
+                  {createDescription(response.description)}
+                </div>
+              )}
+            </div>
+            {responseHeaders && (
+              <Details
+                className="openapi-markdown__details"
+                data-collapsed={true}
+                open={false}
+                style={{ textAlign: "left", marginBottom: "1rem" }}
+                summary={
+                  <summary>
+                    <strong>Response Headers</strong>
+                  </summary>
+                }
+              >
+                <ResponseHeaders responseHeaders={responseHeaders} />
+              </Details>
+            )}
+            <ResponseSchema
+              title="Schema"
+              body={{ content: response.content }}
+            />
+          </TabItem>
+        );
+      })}
+    </ApiTabs>
+  );
+};
+
+export default StatusCodes;

package/src/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/src/theme-classic.d.ts

@@ -27,8 +27,6 @@ declare module "@docusaurus/theme-common/internal" {
   export interface LineProps extends ILineProps {}
   export interface CodeBlockProps extends ICodeBlockProps {}
 
-  export function useDoc();
-
   export function usePrismTheme(): PrismTheme;
 
   export function sanitizeTabsChildren(children: TabProps["children"]);

package/src/theme-openapi.d.ts

@@ -54,6 +54,10 @@ declare module "@theme/ApiItem/hooks" {
 }
 
 declare module "@theme/ApiItem/Layout" {
+  export interface Props {
+    readonly children: JSX.Element;
+  }
+
   export default function Layout(props: any): JSX.Element;
 }