docusaurus-plugin-openapi-docs 1.5.1 → 1.6.0

package/src/markdown/createResponseSchema.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";
@@ -54,54 +58,63 @@ 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,
+            });
+          }
+
+          return undefined;
+        }),
       }),
     ],
   });
@@ -152,11 +165,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 =
@@ -224,15 +237,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) {
@@ -249,12 +274,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
@@ -262,16 +287,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();
     }
   }
 
@@ -279,21 +308,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();
 }
 
 /**
@@ -404,7 +442,8 @@ function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: string[] | boolean
+  required: string[] | boolean,
+  nullable: boolean | unknown
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -419,15 +458,33 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
-              guard(schema.required && schema.required === true, () => [
-                create("strong", {
-                  style: {
-                    fontSize: "var(--ifm-code-font-size)",
-                    color: "var(--openapi-required)",
-                  },
-                  children: " required",
-                }),
-              ]),
+              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)
+                  : required === true,
+                () => [
+                  create("strong", {
+                    style: {
+                      fontSize: "var(--ifm-code-font-size)",
+                      color: "var(--openapi-required)",
+                    },
+                    children: " required",
+                  }),
+                ]
+              ),
             ],
           }),
           create("div", {
@@ -558,7 +615,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 +636,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.writeOnly && mergedSchemas.writeOnly === true) {
@@ -597,29 +684,51 @@ function createEdges({
       collapsible: false,
       name,
       required: false,
-      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.writeOnly && schema.writeOnly === true) {
@@ -631,11 +740,9 @@ function createEdges({
     collapsible: false,
     name,
     required: false,
-    deprecated: schema.deprecated,
-    schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),
-    defaultValue: schema.default,
+    schema: schema,
   });
 }
 
@@ -643,34 +750,41 @@ 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 (mergedSchemas.items !== undefined) {
+      nodes.push(createItems(mergedSchemas));
     }
   }
 
   if (schema.properties !== undefined) {
-    return createProperties(schema);
+    nodes.push(createProperties(schema));
   }
 
-  // Could be set to false to just check if evals to true
-  if (schema.additionalProperties) {
-    return createAdditionalProperties(schema);
+  if (schema.additionalProperties !== undefined) {
+    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 +818,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 {
@@ -738,7 +852,8 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
       children: mimeTypes.map((mimeType: any) => {
         const responseExamples = body.content![mimeType].examples;
         const responseExample = body.content![mimeType].example;
-        const firstBody = body.content![mimeType].schema;
+        const firstBody: any =
+          body.content![mimeType].schema ?? body.content![mimeType];
 
         if (
           firstBody === undefined &&
@@ -776,12 +891,6 @@ export function createResponseSchema({ 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,
                                 () => [

package/src/markdown/createStatusCodes.ts

@@ -62,46 +62,45 @@ function createResponseHeaders(responseHeaders: any) {
     create("ul", {
       style: { marginLeft: "1rem" },
       children: [
-        Object.entries(responseHeaders).map(([headerName, headerObj]) => {
-          const {
-            description,
-            schema: { type },
-            example,
-          }: any = headerObj;
+        Object.entries(responseHeaders).map(
+          ([headerName, headerObj]: [any, any]) => {
+            const { description, example }: any = headerObj;
+            const type = headerObj.schema?.type ?? "any";
 
-          return create("li", {
-            className: "schemaItem",
-            children: [
-              createDetailsSummary({
-                children: [
-                  create("strong", { children: headerName }),
-                  guard(type, () => [
-                    create("span", {
-                      style: { opacity: "0.6" },
-                      children: ` ${type}`,
-                    }),
-                  ]),
-                ],
-              }),
-              create("div", {
-                children: [
-                  guard(description, (description) =>
-                    create("div", {
-                      style: {
-                        marginTop: ".5rem",
-                        marginBottom: ".5rem",
-                      },
-                      children: [
-                        guard(example, () => `Example: ${example}`),
-                        createDescription(description),
-                      ],
-                    })
-                  ),
-                ],
-              }),
-            ],
-          });
-        }),
+            return create("li", {
+              className: "schemaItem",
+              children: [
+                createDetailsSummary({
+                  children: [
+                    create("strong", { children: headerName }),
+                    guard(type, () => [
+                      create("span", {
+                        style: { opacity: "0.6" },
+                        children: ` ${type}`,
+                      }),
+                    ]),
+                  ],
+                }),
+                create("div", {
+                  children: [
+                    guard(description, (description) =>
+                      create("div", {
+                        style: {
+                          marginTop: ".5rem",
+                          marginBottom: ".5rem",
+                        },
+                        children: [
+                          guard(example, () => `Example: ${example}`),
+                          createDescription(description),
+                        ],
+                      })
+                    ),
+                  ],
+                }),
+              ],
+            });
+          }
+        ),
       ],
     })
   );
@@ -120,14 +119,10 @@ export function createResponseExamples(
   }
   return Object.entries(responseExamples).map(
     ([exampleName, exampleValue]: any) => {
-      const camelToSpaceName = exampleName.replace(/([A-Z])/g, " $1");
-      let finalFormattedName =
-        camelToSpaceName.charAt(0).toUpperCase() + camelToSpaceName.slice(1);
-
       if (typeof exampleValue.value === "object") {
         return create("TabItem", {
-          label: `${finalFormattedName}`,
-          value: `${finalFormattedName}`,
+          label: `${exampleName}`,
+          value: `${exampleName}`,
           children: [
             guard(exampleValue.summary, (summary) => [
               create("p", {
@@ -142,8 +137,8 @@ export function createResponseExamples(
         });
       }
       return create("TabItem", {
-        label: `${finalFormattedName}`,
-        value: `${finalFormattedName}`,
+        label: `${exampleName}`,
+        value: `${exampleName}`,
         children: [
           guard(exampleValue.summary, (summary) => [
             create("p", {

package/src/markdown/index.ts

@@ -88,7 +88,7 @@ export function createInfoPageMD({
 }: InfoPageMetadata) {
   return render([
     `import ApiLogo from "@theme/ApiLogo";\n`,
-    `import Tabs from "@theme/Tabs";\n`,
+    `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import TabItem from "@theme/TabItem";\n`,
     `import Export from "@theme/ApiDemoPanel/Export";\n\n`,