docusaurus-plugin-openapi-docs 1.5.1 → 1.6.0

package/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,12 +268,12 @@ 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
@@ -257,16 +281,20 @@ function createItems(schema: SchemaObject) {
       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();
     }
   }
 
@@ -274,21 +302,30 @@ function createItems(schema: SchemaObject) {
     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();
 }
 
 /**
@@ -399,7 +436,8 @@ function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: string[] | boolean
+  required: string[] | boolean,
+  nullable: boolean | unknown
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -414,6 +452,19 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
+              guard(
+                (schema.nullable && schema.nullable === true) ||
+                  (nullable && nullable === true),
+                () => [
+                  create("strong", {
+                    style: {
+                      fontSize: "var(--ifm-code-font-size)",
+                      color: "var(--openapi-nullable)",
+                    },
+                    children: " nullable",
+                  }),
+                ]
+              ),
               guard(
                 Array.isArray(required)
                   ? required.includes(name)
@@ -558,7 +609,13 @@ function createEdges({
   }
 
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.allOf !== undefined) {
@@ -573,20 +630,44 @@ function createEdges({
       mergedSchemas.oneOf !== undefined ||
       mergedSchemas.anyOf !== undefined
     ) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.properties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.additionalProperties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     // array of objects
     if (mergedSchemas.items?.properties !== undefined) {
-      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+      return createDetailsNode(
+        name,
+        mergedSchemaName,
+        mergedSchemas,
+        required,
+        schema.nullable
+      );
     }
 
     if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
@@ -597,29 +678,51 @@ function createEdges({
       collapsible: false,
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
-      deprecated: mergedSchemas.deprecated,
-      schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
-      defaultValue: mergedSchemas.default,
+      schema: mergedSchemas,
     });
   }
 
   if (schema.properties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.additionalProperties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   // array of objects
   if (schema.items?.properties !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.items?.anyOf !== undefined || schema.items?.oneOf !== undefined) {
-    return createDetailsNode(name, schemaName, schema, required);
+    return createDetailsNode(
+      name,
+      schemaName,
+      schema,
+      required,
+      schema.nullable
+    );
   }
 
   if (schema.readOnly && schema.readOnly === true) {
@@ -631,11 +734,9 @@ function createEdges({
     collapsible: false,
     name,
     required: Array.isArray(required) ? required.includes(name) : required,
-    deprecated: schema.deprecated,
-    schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),
-    defaultValue: schema.default,
+    schema: schema,
   });
 }
 
@@ -643,12 +744,13 @@ 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) {
@@ -656,21 +758,25 @@ function createNodes(schema: SchemaObject): any {
 
     // 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
@@ -704,7 +810,7 @@ function createNodes(schema: SchemaObject): any {
 
   // Unknown node/schema type should return undefined
   // So far, haven't seen this hit in testing
-  return undefined;
+  return "any";
 }
 
 interface Props {
@@ -758,12 +864,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: {
@@ -799,7 +899,8 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
   }
 
   const randomFirstKey = Object.keys(body.content)[0];
-  const firstBody = body.content[randomFirstKey].schema;
+  const firstBody: any =
+    body.content[randomFirstKey].schema ?? body.content![randomFirstKey];
 
   if (firstBody === undefined) {
     return undefined;