[Bug] Support multiple same-level node types and improve items/array support (#397)

Author: sserrata

demo/docusaurus.config.js

@@ -239,6 +239,14 @@ const config = {
             specPath: "examples/food/yogurtstore/openapi.yaml",
             outputDir: "docs/food/yogurtstore",
           },
+          config: {
+            specPath:
+              "https://raw.githubusercontent.com/PaloAltoNetworks/pan.dev/master/openapi-specs/access/prisma-access-config/AddressGroups.yaml",
+            outputDir: "docs/config",
+            sidebarOptions: {
+              groupPathsBy: "tag",
+            },
+          },
         },
       },
     ],

demo/sidebars.js

@@ -70,6 +70,16 @@ const sidebars = {
       },
       items: require("./docs/cos/sidebar.js"),
     },
+    {
+      type: "category",
+      label: "Address Groups",
+      link: {
+        type: "generated-index",
+        title: "Address Groups",
+        slug: "/category/config-api",
+      },
+      items: require("./docs/config/sidebar.js"),
+    },
     {
       type: "category",
       label: "Burgers",

packages/docusaurus-plugin-openapi-docs/src/markdown/createArrayBracket.ts

@@ -0,0 +1,35 @@
+/* ============================================================================
+ * 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 { create } from "./utils";
+
+export function createOpeningArrayBracket() {
+  return create("li", {
+    children: create("div", {
+      style: {
+        fontSize: "var(--ifm-code-font-size)",
+        opacity: "0.6",
+        marginLeft: "-.5rem",
+        paddingBottom: ".5rem",
+      },
+      children: ["Array ["],
+    }),
+  });
+}
+
+export function createClosingArrayBracket() {
+  return create("li", {
+    children: create("div", {
+      style: {
+        fontSize: "var(--ifm-code-font-size)",
+        opacity: "0.6",
+        marginLeft: "-.5rem",
+      },
+      children: ["]"],
+    }),
+  });
+}

packages/docusaurus-plugin-openapi-docs/src/markdown/createRequestSchema.ts

@@ -6,6 +6,10 @@
  * ========================================================================== */
 
 import { MediaTypeObject, SchemaObject } from "../openapi/types";
+import {
+  createClosingArrayBracket,
+  createOpeningArrayBracket,
+} from "./createArrayBracket";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
@@ -49,54 +53,62 @@ export function mergeAllOf(allOf: SchemaObject[]) {
  */
 function createAnyOneOf(schema: SchemaObject): any {
   const type = schema.oneOf ? "oneOf" : "anyOf";
-  return create("div", {
+  return create("li", {
     children: [
-      create("div", {
-        children: [
-          create("span", {
-            className: "badge badge--info",
-            children: type,
-          }),
-          create("SchemaTabs", {
-            children: schema[type]!.map((anyOneSchema, index) => {
-              const label = anyOneSchema.title
-                ? anyOneSchema.title
-                : `MOD${index + 1}`;
-              const anyOneChildren = [];
-
-              if (anyOneSchema.properties !== undefined) {
-                anyOneChildren.push(createProperties(anyOneSchema));
-              }
-
-              if (anyOneSchema.allOf !== undefined) {
-                anyOneChildren.push(createNodes(anyOneSchema));
-              }
-
-              if (anyOneSchema.items !== undefined) {
-                anyOneChildren.push(createItems(anyOneSchema));
-              }
-
-              if (
-                anyOneSchema.type === "string" ||
-                anyOneSchema.type === "number" ||
-                anyOneSchema.type === "integer" ||
-                anyOneSchema.type === "boolean"
-              ) {
-                anyOneChildren.push(createNodes(anyOneSchema));
-              }
-
-              if (anyOneChildren.length) {
-                return create("TabItem", {
-                  label: label,
-                  value: `${index}-item-properties`,
-                  children: anyOneChildren,
-                });
-              }
-
-              return undefined;
-            }),
-          }),
-        ],
+      create("span", {
+        className: "badge badge--info",
+        children: type,
+      }),
+      create("SchemaTabs", {
+        children: schema[type]!.map((anyOneSchema, index) => {
+          const label = anyOneSchema.title
+            ? anyOneSchema.title
+            : `MOD${index + 1}`;
+          const anyOneChildren = [];
+
+          if (anyOneSchema.properties !== undefined) {
+            anyOneChildren.push(createProperties(anyOneSchema));
+          }
+
+          if (anyOneSchema.allOf !== undefined) {
+            anyOneChildren.push(createNodes(anyOneSchema));
+          }
+
+          if (anyOneSchema.items !== undefined) {
+            anyOneChildren.push(createItems(anyOneSchema));
+          }
+
+          if (
+            anyOneSchema.type === "string" ||
+            anyOneSchema.type === "number" ||
+            anyOneSchema.type === "integer" ||
+            anyOneSchema.type === "boolean"
+          ) {
+            anyOneChildren.push(createNodes(anyOneSchema));
+          }
+          if (anyOneChildren.length) {
+            if (schema.type === "array") {
+              return create("TabItem", {
+                label: label,
+                value: `${index}-item-properties`,
+                children: [
+                  createOpeningArrayBracket(),
+                  anyOneChildren,
+                  createClosingArrayBracket(),
+                ]
+                  .filter(Boolean)
+                  .flat(),
+              });
+            }
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-properties`,
+              children: anyOneChildren.filter(Boolean).flat(),
+            });
+          }
+
+          return undefined;
+        }),
       }),
     ],
   });
@@ -147,11 +159,11 @@ function createAdditionalProperties(schema: SchemaObject) {
   // }
 
   if (
-    schema.additionalProperties?.type === "string" ||
-    schema.additionalProperties?.type === "object" ||
-    schema.additionalProperties?.type === "boolean" ||
-    schema.additionalProperties?.type === "integer" ||
-    schema.additionalProperties?.type === "number"
+    (schema.additionalProperties?.type as string) === "string" ||
+    (schema.additionalProperties?.type as string) === "object" ||
+    (schema.additionalProperties?.type as string) === "boolean" ||
+    (schema.additionalProperties?.type as string) === "integer" ||
+    (schema.additionalProperties?.type as string) === "number"
   ) {
     const type = schema.additionalProperties?.type;
     const additionalProperties =
@@ -219,15 +231,27 @@ function createAdditionalProperties(schema: SchemaObject) {
 // TODO: figure out how to handle array of objects
 function createItems(schema: SchemaObject) {
   if (schema.items?.properties !== undefined) {
-    return createProperties(schema.items);
+    return [
+      createOpeningArrayBracket(),
+      createProperties(schema.items),
+      createClosingArrayBracket(),
+    ].flat();
   }
 
   if (schema.items?.additionalProperties !== undefined) {
-    return createAdditionalProperties(schema.items);
+    return [
+      createOpeningArrayBracket(),
+      createAdditionalProperties(schema.items),
+      createClosingArrayBracket(),
+    ].flat();
   }
 
   if (schema.items?.oneOf !== undefined || schema.items?.anyOf !== undefined) {
-    return createAnyOneOf(schema.items!);
+    return [
+      createOpeningArrayBracket(),
+      createAnyOneOf(schema.items!),
+      createClosingArrayBracket(),
+    ].flat();
   }
 
   if (schema.items?.allOf !== undefined) {
@@ -244,51 +268,64 @@ function createItems(schema: SchemaObject) {
         mergedSchemas.anyOf !== undefined) &&
       mergedSchemas.properties
     ) {
-      return create("div", {
-        children: [
-          createAnyOneOf(mergedSchemas),
-          createProperties(mergedSchemas),
-        ],
-      });
+      return [
+        createOpeningArrayBracket(),
+        createAnyOneOf(mergedSchemas),
+        createProperties(mergedSchemas),
+        createClosingArrayBracket(),
+      ].flat();
     }
 
     // Handles only anyOf/oneOf
     if (
       mergedSchemas.oneOf !== undefined ||
       mergedSchemas.anyOf !== undefined
     ) {
-      return create("div", {
-        children: [createAnyOneOf(mergedSchemas)],
-      });
+      return [
+        createOpeningArrayBracket(),
+        createAnyOneOf(mergedSchemas),
+        createClosingArrayBracket(),
+      ].flat();
     }
 
     // Handles properties
     if (mergedSchemas.properties !== undefined) {
-      return create("div", {
-        children: [createProperties(mergedSchemas)],
-      });
+      return [
+        createOpeningArrayBracket(),
+        createProperties(mergedSchemas),
+        createClosingArrayBracket(),
+      ].flat();
     }
   }
 
   if (
     schema.items?.type === "string" ||
     schema.items?.type === "number" ||
     schema.items?.type === "integer" ||
-    schema.items?.type === "boolean"
+    schema.items?.type === "boolean" ||
+    schema.items?.type === "object"
   ) {
-    return createNodes(schema.items);
+    return [
+      createOpeningArrayBracket(),
+      createNodes(schema.items),
+      createClosingArrayBracket(),
+    ].flat();
   }
 
   // TODO: clean this up or eliminate it?
-  return Object.entries(schema.items!).map(([key, val]) =>
-    createEdges({
-      name: key,
-      schema: val,
-      required: Array.isArray(schema.required)
-        ? schema.required.includes(key)
-        : false,
-    })
-  );
+  return [
+    createOpeningArrayBracket(),
+    Object.entries(schema.items!).map(([key, val]) =>
+      createEdges({
+        name: key,
+        schema: val,
+        required: Array.isArray(schema.required)
+          ? schema.required.includes(key)
+          : false,
+      })
+    ),
+    createClosingArrayBracket(),
+  ].flat();
 }
 
 /**
@@ -648,34 +685,39 @@ function createEdges({
  * Creates a hierarchical level of a schema tree. Nodes produce edges that can branch into sub-nodes with edges, recursively.
  */
 function createNodes(schema: SchemaObject): any {
+  const nodes = [];
   // if (schema.discriminator !== undefined) {
   //   return createDiscriminator(schema);
   // }
 
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
-    return createAnyOneOf(schema);
+    nodes.push(createAnyOneOf(schema));
   }
 
   if (schema.allOf !== undefined) {
     const { mergedSchemas } = mergeAllOf(schema.allOf);
 
     // allOf seems to always result in properties
     if (mergedSchemas.properties !== undefined) {
-      return createProperties(mergedSchemas);
+      nodes.push(createProperties(mergedSchemas));
     }
   }
 
   if (schema.properties !== undefined) {
-    return createProperties(schema);
+    nodes.push(createProperties(schema));
   }
 
   if (schema.additionalProperties !== undefined) {
-    return createAdditionalProperties(schema);
+    nodes.push(createAdditionalProperties(schema));
   }
 
   // TODO: figure out how to handle array of objects
   if (schema.items !== undefined) {
-    return createItems(schema);
+    nodes.push(createItems(schema));
+  }
+
+  if (nodes.length && nodes.length > 0) {
+    return nodes.filter(Boolean).flat();
   }
 
   // primitive
@@ -763,12 +805,6 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
                   style: { textAlign: "left" },
                   children: [
                     create("strong", { children: `${title}` }),
-                    guard(firstBody.type === "array", (format) =>
-                      create("span", {
-                        style: { opacity: "0.6" },
-                        children: ` array`,
-                      })
-                    ),
                     guard(body.required && body.required === true, () => [
                       create("strong", {
                         style: {