docusaurus-plugin-openapi-docs 1.0.6 → 1.1.2

package/src/markdown/createSchemaDetails.ts

@@ -12,12 +12,13 @@ import { createDetailsSummary } from "./createDetailsSummary";
 import { getQualifierMessage, getSchemaName } from "./schema";
 import { create, guard } from "./utils";
 
-const mergeAllOf = require("json-schema-merge-allof");
+const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 
-function resolveAllOf(allOf: SchemaObject[]) {
-  // Use external library to resolve and merge nested allOf schemas
-  let properties: SchemaObject = {};
-  const mergedSchemas = mergeAllOf(allOf, {
+/**
+ * Returns a merged representation of allOf array of schemas.
+ */
+function mergeAllOf(allOf: SchemaObject[]) {
+  const mergedSchemas = jsonSchemaMergeAllOf(allOf, {
     resolvers: {
       readOnly: function () {
         return true;
@@ -28,205 +29,444 @@ function resolveAllOf(allOf: SchemaObject[]) {
     },
   });
 
-  if (mergedSchemas.properties) {
-    properties = mergedSchemas.properties;
-  }
-
   const required = allOf.reduce((acc, cur) => {
     if (Array.isArray(cur.required)) {
       const next = [...acc, ...cur.required];
       return next;
     }
     return acc;
-  }, [] as string[]);
+  }, [] as any);
 
-  return { properties, required };
+  return { mergedSchemas, required };
 }
 
-interface RowProps {
-  name: string;
-  schema: SchemaObject;
-  required: boolean;
+/**
+ * For handling nested anyOf/oneOf.
+ */
+function createAnyOneOf(schema: SchemaObject): any {
+  const type = schema.oneOf ? "oneOf" : "anyOf";
+  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;
+            }),
+          }),
+        ],
+      }),
+    ],
+  });
 }
 
-function createRow({ name, schema, required }: RowProps) {
-  const schemaName = getSchemaName(schema, true);
-  if (schemaName && (schemaName === "object" || schemaName === "object[]")) {
-    return create("SchemaItem", {
-      collapsible: true,
-      className: "schemaItem",
-      children: [
-        createDetails({
+function createProperties(schema: SchemaObject) {
+  return Object.entries(schema.properties!).map(([key, val]) =>
+    createEdges({
+      name: key,
+      schema: val,
+      required: Array.isArray(schema.required)
+        ? schema.required.includes(key)
+        : false,
+    })
+  );
+}
+
+function createAdditionalProperties(schema: SchemaObject) {
+  // TODO?:
+  //   {
+  //   description: 'Integration configuration. See \n' +
+  //     '[Integration Configurations](https://prisma.pan.dev/api/cloud/api-integration-config/).\n',
+  //   example: { webhookUrl: 'https://hooks.slack.com/abcdef' },
+  //   externalDocs: { url: 'https://prisma.pan.dev/api/cloud/api-integration-config' },
+  //   type: 'object'
+  // }
+
+  // TODO?:
+  // {
+  // items: {
+  //     properties: {
+  //       aliasField: [Object],
+  //       displayName: [Object],
+  //       fieldName: [Object],
+  //       maxLength: [Object],
+  //       options: [Object],
+  //       redlockMapping: [Object],
+  //       required: [Object],
+  //       type: [Object],
+  //       typeaheadUri: [Object],
+  //       value: [Object]
+  //     },
+  //     type: 'object'
+  //   },
+  //   type: 'array'
+  // }
+
+  if (
+    schema.additionalProperties?.type === "string" ||
+    schema.additionalProperties?.type === "object" ||
+    schema.additionalProperties?.type === "boolean" ||
+    schema.additionalProperties?.type === "integer" ||
+    schema.additionalProperties?.type === "number"
+  ) {
+    const type = schema.additionalProperties?.type;
+    const additionalProperties =
+      schema.additionalProperties?.additionalProperties;
+    if (additionalProperties !== undefined) {
+      const type = schema.additionalProperties?.additionalProperties?.type;
+      const format = schema.additionalProperties?.additionalProperties?.format;
+      return create("li", {
+        children: create("div", {
           children: [
-            createDetailsSummary({
-              children: [
-                create("strong", { children: name }),
-                create("span", {
-                  style: { opacity: "0.6" },
-                  children: ` ${schemaName}`,
-                }),
-                guard(required, () => [
-                  create("strong", {
-                    style: {
-                      fontSize: "var(--ifm-code-font-size)",
-                      color: "var(--openapi-required)",
-                    },
-                    children: " required",
-                  }),
-                ]),
-              ],
-            }),
-            create("div", {
-              style: { marginLeft: "1rem" },
-              children: [
-                guard(getQualifierMessage(schema), (message) =>
-                  create("div", {
-                    style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                    children: createDescription(message),
-                  })
-                ),
-                guard(schema.description, (description) =>
-                  create("div", {
-                    style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                    children: createDescription(description),
-                  })
-                ),
-                createRows({ schema: schema }),
-              ],
-            }),
+            create("code", { children: `property name*` }),
+            guard(type, (type) =>
+              create("span", {
+                style: { opacity: "0.6" },
+                children: ` ${type}`,
+              })
+            ),
+            guard(format, (format) =>
+              create("span", {
+                style: { opacity: "0.6" },
+                children: ` (${format})`,
+              })
+            ),
+            guard(getQualifierMessage(schema.additionalProperties), (message) =>
+              create("div", {
+                style: { marginTop: "var(--ifm-table-cell-padding)" },
+                children: createDescription(message),
+              })
+            ),
           ],
         }),
-      ],
+      });
+    }
+    return create("li", {
+      children: create("div", {
+        children: [
+          create("code", { children: `property name*` }),
+          guard(type, (type) =>
+            create("span", {
+              style: { opacity: "0.6" },
+              children: ` ${type}`,
+            })
+          ),
+          guard(getQualifierMessage(schema.additionalProperties), (message) =>
+            create("div", {
+              style: { marginTop: "var(--ifm-table-cell-padding)" },
+              children: createDescription(message),
+            })
+          ),
+        ],
+      }),
     });
   }
+  return Object.entries(schema.additionalProperties!).map(([key, val]) =>
+    createEdges({
+      name: key,
+      schema: val,
+      required: Array.isArray(schema.required)
+        ? schema.required.includes(key)
+        : false,
+    })
+  );
+}
+
+// TODO: figure out how to handle array of objects
+function createItems(schema: SchemaObject) {
+  if (schema.items?.properties !== undefined) {
+    return createProperties(schema.items);
+  }
+
+  if (schema.items?.additionalProperties !== undefined) {
+    return createAdditionalProperties(schema.items);
+  }
+
+  if (schema.items?.oneOf !== undefined || schema.items?.anyOf !== undefined) {
+    return createAnyOneOf(schema.items!);
+  }
+
+  if (schema.items?.allOf !== undefined) {
+    const { mergedSchemas }: { mergedSchemas: SchemaObject; required: any } =
+      mergeAllOf(schema.items?.allOf);
+
+    // Handles combo anyOf/oneOf + properties
+    if (
+      (mergedSchemas.oneOf !== undefined ||
+        mergedSchemas.anyOf !== undefined) &&
+      mergedSchemas.properties
+    ) {
+      return create("div", {
+        children: [
+          createAnyOneOf(mergedSchemas),
+          createProperties(mergedSchemas),
+        ],
+      });
+    }
+
+    // Handles only anyOf/oneOf
+    if (
+      mergedSchemas.oneOf !== undefined ||
+      mergedSchemas.anyOf !== undefined
+    ) {
+      return create("div", {
+        children: [
+          createAnyOneOf(mergedSchemas),
+          createProperties(mergedSchemas),
+        ],
+      });
+    }
+  }
+
+  if (
+    schema.items?.type === "string" ||
+    schema.items?.type === "number" ||
+    schema.items?.type === "integer" ||
+    schema.items?.type === "boolean"
+  ) {
+    return createNodes(schema.items);
+  }
 
+  // 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,
+    })
+  );
+}
+
+function createDetailsNode(
+  name: string,
+  schemaName: string,
+  schema: SchemaObject,
+  required: any
+): any {
   return create("SchemaItem", {
-    collapsible: false,
-    name,
-    required,
-    schemaDescription: schema.description,
-    schemaName: getSchemaName(schema, true),
-    qualifierMessage: getQualifierMessage(schema),
+    collapsible: true,
+    className: "schemaItem",
+    children: [
+      createDetails({
+        children: [
+          createDetailsSummary({
+            children: [
+              create("strong", { children: name }),
+              create("span", {
+                style: { opacity: "0.6" },
+                children: ` ${schemaName}`,
+              }),
+              guard(required, () => [
+                create("strong", {
+                  style: {
+                    fontSize: "var(--ifm-code-font-size)",
+                    color: "var(--openapi-required)",
+                  },
+                  children: " required",
+                }),
+              ]),
+            ],
+          }),
+          create("div", {
+            style: { marginLeft: "1rem" },
+            children: [
+              guard(getQualifierMessage(schema), (message) =>
+                create("div", {
+                  style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                  children: createDescription(message),
+                })
+              ),
+              guard(schema.description, (description) =>
+                create("div", {
+                  style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                  children: createDescription(description),
+                })
+              ),
+              createNodes(schema),
+            ],
+          }),
+        ],
+      }),
+    ],
   });
 }
 
-interface RowsProps {
+interface EdgeProps {
+  name: string;
   schema: SchemaObject;
+  required: boolean;
 }
 
-function createRows({ schema }: RowsProps): string | undefined {
-  // object
-  if (schema.properties !== undefined) {
-    return create("ul", {
-      children: Object.entries(schema.properties).map(([key, val]) =>
-        createRow({
-          name: key,
-          schema: val,
-          required: Array.isArray(schema.required)
-            ? schema.required.includes(key)
-            : false,
-        })
-      ),
-    });
+/**
+ * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
+ */
+function createEdges({ name, schema, required }: EdgeProps): any {
+  const schemaName = getSchemaName(schema);
+
+  if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
+    return createDetailsNode(name, schemaName, schema, required);
   }
 
-  // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
   if (schema.allOf !== undefined) {
-    const { properties, required } = resolveAllOf(schema.allOf);
-    return create("div", {
-      children: [
-        create("span", {
-          className: "badge badge--info",
-          style: { marginBottom: "1rem" },
-          children: "allOf",
-        }),
-        create("ul", {
-          className: "allOf",
-          children: Object.entries(properties).map(([key, val]) =>
-            createRow({
-              name: key,
-              schema: val,
-              required: Array.isArray(required)
-                ? required.includes(key)
-                : false,
-            })
-          ),
-        }),
-      ],
+    const {
+      mergedSchemas,
+      required,
+    }: { mergedSchemas: SchemaObject; required: any } = mergeAllOf(
+      schema.allOf
+    );
+    const mergedSchemaName = getSchemaName(mergedSchemas);
+
+    if (
+      mergedSchemas.oneOf !== undefined ||
+      mergedSchemas.anyOf !== undefined
+    ) {
+      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+    }
+
+    if (mergedSchemas.properties !== undefined) {
+      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+    }
+
+    if (mergedSchemas.additionalProperties !== undefined) {
+      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+    }
+
+    return create("SchemaItem", {
+      collapsible: false,
+      name,
+      required,
+      schemaDescription: mergedSchemas.description,
+      schemaName: schemaName,
+      qualifierMessage: getQualifierMessage(schema),
     });
   }
 
-  // array
-  if (schema.items !== undefined) {
-    return createRows({ schema: schema.items });
+  if (schema.properties !== undefined) {
+    return createDetailsNode(name, schemaName, schema, required);
   }
 
-  // primitive
-  return undefined;
-}
+  if (schema.additionalProperties !== undefined) {
+    return createDetailsNode(name, schemaName, schema, required);
+  }
 
-interface RowsRootProps {
-  schema: SchemaObject;
+  // array of objects
+  if (schema.items?.properties !== undefined) {
+    return createDetailsNode(name, schemaName, schema, required);
+  }
+
+  // primitives and array of non-objects
+  return create("SchemaItem", {
+    collapsible: false,
+    name,
+    required,
+    schemaDescription: schema.description,
+    schemaName: schemaName,
+    qualifierMessage: getQualifierMessage(schema),
+  });
 }
 
-function createRowsRoot({ schema }: RowsRootProps) {
-  // object
-  if (schema.properties !== undefined) {
-    return Object.entries(schema.properties).map(([key, val]) =>
-      createRow({
-        name: key,
-        schema: val,
-        required: Array.isArray(schema.required)
-          ? schema.required.includes(key)
-          : false,
-      })
-    );
+/**
+ * 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 {
+  if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
+    return createAnyOneOf(schema);
   }
 
-  // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
   if (schema.allOf !== undefined) {
-    const { properties, required } = resolveAllOf(schema.allOf);
-    return Object.entries(properties).map(([key, val]) =>
-      createRow({
-        name: key,
-        schema: val,
-        required: Array.isArray(required) ? required.includes(key) : false,
-      })
-    );
+    const { mergedSchemas } = mergeAllOf(schema.allOf);
+
+    // allOf seems to always result in properties
+    if (mergedSchemas.properties !== undefined) {
+      return createProperties(mergedSchemas);
+    }
+  }
+
+  if (schema.properties !== undefined) {
+    return createProperties(schema);
   }
 
-  // array
+  if (schema.additionalProperties !== undefined) {
+    return createAdditionalProperties(schema);
+  }
+
+  // TODO: figure out how to handle array of objects
   if (schema.items !== undefined) {
+    return createItems(schema);
+  }
+
+  // primitive
+  if (schema.type !== undefined) {
     return create("li", {
       children: create("div", {
-        children: [createRows({ schema: schema.items })],
+        children: [
+          create("strong", { children: schema.type }),
+          guard(schema.format, (format) =>
+            create("span", {
+              style: { opacity: "0.6" },
+              children: ` ${format}`,
+            })
+          ),
+          guard(getQualifierMessage(schema), (message) =>
+            create("div", {
+              style: { marginTop: "var(--ifm-table-cell-padding)" },
+              children: createDescription(message),
+            })
+          ),
+          guard(schema.description, (description) =>
+            create("div", {
+              style: { marginTop: "var(--ifm-table-cell-padding)" },
+              children: createDescription(description),
+            })
+          ),
+        ],
       }),
     });
   }
 
-  // primitive
-  return create("li", {
-    children: create("div", {
-      children: [
-        create("span", {
-          style: { opacity: "0.6" },
-          children: ` ${schema.type}`,
-        }),
-        guard(getQualifierMessage(schema), (message) =>
-          create("div", {
-            style: { marginTop: "var(--ifm-table-cell-padding)" },
-            children: createDescription(message),
-          })
-        ),
-        guard(schema.description, (description) =>
-          create("div", {
-            style: { marginTop: "var(--ifm-table-cell-padding)" },
-            children: createDescription(description),
-          })
-        ),
-      ],
-    }),
-  });
+  // Unknown node/schema type should return undefined
+  // So far, haven't seen this hit in testing
+  return undefined;
 }
 
 interface Props {
@@ -251,7 +491,6 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
     return undefined;
   }
 
-  // TODO:
   // NOTE: We just pick a random content-type.
   // How common is it to have multiple?
   const randomFirstKey = Object.keys(body.content)[0];
@@ -268,6 +507,7 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
     }
   }
 
+  // Root-level schema dropdown
   return createDetails({
     "data-collapsed": false,
     open: true,
@@ -277,6 +517,12 @@ export function createSchemaDetails({ 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, () => [
             create("strong", {
               style: {
@@ -301,7 +547,7 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
       }),
       create("ul", {
         style: { marginLeft: "1rem" },
-        children: createRowsRoot({ schema: firstBody }),
+        children: createNodes(firstBody),
       }),
     ],
   });

package/src/markdown/index.ts

@@ -40,6 +40,7 @@ export function createApiPageMD({
     `import ParamsItem from "@theme/ParamsItem";\n`,
     `import SchemaItem from "@theme/SchemaItem"\n`,
     `import ApiTabs from "@theme/ApiTabs";\n`,
+    `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),