docusaurus-plugin-openapi-docs 1.5.1 → 1.5.2

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();
 }
 
 /**
@@ -419,6 +457,15 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
+              guard(schema.nullable && schema.nullable === true, () => [
+                create("strong", {
+                  style: {
+                    fontSize: "var(--ifm-code-font-size)",
+                    color: "var(--openapi-nullable)",
+                  },
+                  children: " nullable",
+                }),
+              ]),
               guard(schema.required && schema.required === true, () => [
                 create("strong", {
                   style: {
@@ -597,11 +644,9 @@ function createEdges({
       collapsible: false,
       name,
       required: false,
-      deprecated: mergedSchemas.deprecated,
-      schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
-      defaultValue: mergedSchemas.default,
+      schema: mergedSchemas,
     });
   }
 
@@ -631,11 +676,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 +686,42 @@ 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
@@ -776,12 +827,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

@@ -120,14 +120,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 +138,8 @@ export function createResponseExamples(
         });
       }
       return create("TabItem", {
-        label: `${finalFormattedName}`,
-        value: `${finalFormattedName}`,
+        label: `${exampleName}`,
+        value: `${exampleName}`,
         children: [
           guard(exampleValue.summary, (summary) => [
             create("p", {

package/src/openapi/createRequestExample.ts

@@ -6,6 +6,7 @@
  * ========================================================================== */
 
 import chalk from "chalk";
+import merge from "lodash/merge";
 
 import { mergeAllOf } from "../markdown/createRequestSchema";
 import { SchemaObject } from "./types";
@@ -77,18 +78,30 @@ function sampleRequestFromProp(name: string, prop: any, obj: any): any {
 
 export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
   try {
-    let { type, example, allOf, properties, items, oneOf, anyOf } = schema;
+    // deep copy schema before processing
+    let schemaCopy = JSON.parse(JSON.stringify(schema));
+    let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
 
     if (example !== undefined) {
       return example;
     }
 
     if (oneOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, oneOf[0]);
+        delete combinedSchemas.oneOf;
+        return sampleRequestFromSchema(combinedSchemas);
+      }
       // Just go with first schema
       return sampleRequestFromSchema(oneOf[0]);
     }
 
     if (anyOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, anyOf[0]);
+        delete combinedSchemas.anyOf;
+        return sampleRequestFromSchema(combinedSchemas);
+      }
       // Just go with first schema
       return sampleRequestFromSchema(anyOf[0]);
     }
@@ -103,6 +116,11 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
           }
         }
       }
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, mergedSchemas);
+        delete combinedSchemas.allOf;
+        return sampleRequestFromSchema(combinedSchemas);
+      }
       return sampleRequestFromSchema(mergedSchemas);
     }
 
@@ -118,9 +136,9 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
 
     if (type === "object") {
       let obj: any = {};
-      for (let [name, prop] of Object.entries(properties ?? {})) {
+      for (let [name, prop] of Object.entries(properties ?? {}) as any) {
         if (prop.properties) {
-          for (const [key, value] of Object.entries(prop.properties)) {
+          for (const [key, value] of Object.entries(prop.properties) as any) {
             if (
               (value.readOnly && value.readOnly === true) ||
               value.deprecated
@@ -131,7 +149,9 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
         }
 
         if (prop.items && prop.items.properties) {
-          for (const [key, value] of Object.entries(prop.items.properties)) {
+          for (const [key, value] of Object.entries(
+            prop.items.properties
+          ) as any) {
             if (
               (value.readOnly && value.readOnly === true) ||
               value.deprecated
@@ -157,28 +177,31 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
 
     if (type === "array") {
       if (Array.isArray(items?.anyOf)) {
-        return items?.anyOf.map((item) => sampleRequestFromSchema(item));
+        return items?.anyOf.map((item: any) => sampleRequestFromSchema(item));
       }
 
       if (Array.isArray(items?.oneOf)) {
-        return items?.oneOf.map((item) => sampleRequestFromSchema(item));
+        return items?.oneOf.map((item: any) => sampleRequestFromSchema(item));
       }
 
       return [sampleRequestFromSchema(items)];
     }
 
-    if (schema.enum) {
-      if (schema.default) {
-        return schema.default;
+    if (schemaCopy.enum) {
+      if (schemaCopy.default) {
+        return schemaCopy.default;
       }
-      return normalizeArray(schema.enum)[0];
+      return normalizeArray(schemaCopy.enum)[0];
     }
 
-    if ((schema.readOnly && schema.readOnly === true) || schema.deprecated) {
+    if (
+      (schema.readOnly && schema.readOnly === true) ||
+      schemaCopy.deprecated
+    ) {
       return undefined;
     }
 
-    return primitive(schema);
+    return primitive(schemaCopy);
   } catch (err) {
     console.error(
       chalk.yellow("WARNING: failed to create example from schema object:", err)

package/src/openapi/createResponseExample.ts

@@ -6,6 +6,7 @@
  * ========================================================================== */
 
 import chalk from "chalk";
+import merge from "lodash/merge";
 
 import { mergeAllOf } from "../markdown/createResponseSchema";
 import { SchemaObject } from "./types";
@@ -77,7 +78,9 @@ function sampleResponseFromProp(name: string, prop: any, obj: any): any {
 
 export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
   try {
-    let { type, example, allOf, oneOf, anyOf, properties, items } = schema;
+    // deep copy schema before processing
+    let schemaCopy = JSON.parse(JSON.stringify(schema));
+    let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
 
     if (example !== undefined) {
       return example;
@@ -96,15 +99,30 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
           }
         }
       }
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, mergedSchemas);
+        delete combinedSchemas.allOf;
+        return sampleResponseFromSchema(combinedSchemas);
+      }
       return sampleResponseFromSchema(mergedSchemas);
     }
 
     if (oneOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, oneOf[0]);
+        delete combinedSchemas.oneOf;
+        return sampleResponseFromSchema(combinedSchemas);
+      }
       // Just go with first schema
       return sampleResponseFromSchema(oneOf[0]);
     }
 
     if (anyOf) {
+      if (properties) {
+        const combinedSchemas = merge(schemaCopy, anyOf[0]);
+        delete combinedSchemas.anyOf;
+        return sampleResponseFromSchema(combinedSchemas);
+      }
       // Just go with first schema
       return sampleResponseFromSchema(anyOf[0]);
     }
@@ -121,9 +139,9 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
 
     if (type === "object") {
       let obj: any = {};
-      for (let [name, prop] of Object.entries(properties ?? {})) {
+      for (let [name, prop] of Object.entries(properties ?? {}) as any) {
         if (prop.properties) {
-          for (const [key, value] of Object.entries(prop.properties)) {
+          for (const [key, value] of Object.entries(prop.properties) as any) {
             if (
               (value.writeOnly && value.writeOnly === true) ||
               value.deprecated
@@ -134,7 +152,9 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
         }
 
         if (prop.items && prop.items.properties) {
-          for (const [key, value] of Object.entries(prop.items.properties)) {
+          for (const [key, value] of Object.entries(
+            prop.items.properties
+          ) as any) {
             if (
               (value.writeOnly && value.writeOnly === true) ||
               value.deprecated
@@ -160,28 +180,31 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
 
     if (type === "array") {
       if (Array.isArray(items?.anyOf)) {
-        return items?.anyOf.map((item) => sampleResponseFromSchema(item));
+        return items?.anyOf.map((item: any) => sampleResponseFromSchema(item));
       }
 
       if (Array.isArray(items?.oneOf)) {
-        return items?.oneOf.map((item) => sampleResponseFromSchema(item));
+        return items?.oneOf.map((item: any) => sampleResponseFromSchema(item));
       }
 
       return [sampleResponseFromSchema(items)];
     }
 
-    if (schema.enum) {
-      if (schema.default) {
-        return schema.default;
+    if (schemaCopy.enum) {
+      if (schemaCopy.default) {
+        return schemaCopy.default;
       }
-      return normalizeArray(schema.enum)[0];
+      return normalizeArray(schemaCopy.enum)[0];
     }
 
-    if ((schema.writeOnly && schema.writeOnly === true) || schema.deprecated) {
+    if (
+      (schemaCopy.writeOnly && schemaCopy.writeOnly === true) ||
+      schemaCopy.deprecated
+    ) {
       return undefined;
     }
 
-    return primitive(schema);
+    return primitive(schemaCopy);
   } catch (err) {
     console.error(
       chalk.yellow("WARNING: failed to create example from schema object:", err)