docusaurus-plugin-openapi-docs 1.1.2 → 1.1.5

package/src/markdown/{createSchemaDetails.ts → createResponseSchema.ts}

@@ -99,6 +99,7 @@ function createAnyOneOf(schema: SchemaObject): any {
 }
 
 function createProperties(schema: SchemaObject) {
+  const discriminator = schema.discriminator;
   return Object.entries(schema.properties!).map(([key, val]) =>
     createEdges({
       name: key,
@@ -106,6 +107,7 @@ function createProperties(schema: SchemaObject) {
       required: Array.isArray(schema.required)
         ? schema.required.includes(key)
         : false,
+      discriminator,
     })
   );
 }
@@ -225,8 +227,12 @@ function createItems(schema: SchemaObject) {
   }
 
   if (schema.items?.allOf !== undefined) {
-    const { mergedSchemas }: { mergedSchemas: SchemaObject; required: any } =
-      mergeAllOf(schema.items?.allOf);
+    // TODO: figure out if and how we should pass merged required array
+    const {
+      mergedSchemas,
+    }: { mergedSchemas: SchemaObject; required: string[] } = mergeAllOf(
+      schema.items?.allOf
+    );
 
     // Handles combo anyOf/oneOf + properties
     if (
@@ -277,11 +283,115 @@ function createItems(schema: SchemaObject) {
   );
 }
 
+/**
+ * For handling discriminators that do not map to a same-level property
+ */
+function createDiscriminator(schema: SchemaObject) {
+  const discriminator = schema.discriminator;
+  const propertyName = discriminator?.propertyName;
+  const propertyType = "string"; // should always be string
+  const mapping: any = discriminator?.mapping;
+
+  // Explicit mapping is required since we can't support implicit
+  if (mapping === undefined) {
+    return undefined;
+  }
+
+  // Attempt to get the property description we want to display
+  // TODO: how to make it predictable when handling allOf
+  let propertyDescription;
+  const firstMappingSchema = mapping[Object.keys(mapping)[0]];
+  if (firstMappingSchema.properties !== undefined) {
+    propertyDescription =
+      firstMappingSchema.properties![propertyName!].description;
+  }
+  if (firstMappingSchema.allOf !== undefined) {
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      firstMappingSchema.allOf
+    );
+    if (mergedSchemas.properties !== undefined) {
+      propertyDescription =
+        mergedSchemas.properties[propertyName!]?.description;
+    }
+  }
+
+  if (propertyDescription === undefined) {
+    if (
+      schema.properties !== undefined &&
+      schema.properties![propertyName!] !== undefined
+    ) {
+      propertyDescription = schema.properties![propertyName!].description;
+    }
+  }
+
+  return create("div", {
+    className: "discriminatorItem",
+    children: create("div", {
+      children: [
+        create("strong", {
+          style: { paddingLeft: "1rem" },
+          children: propertyName,
+        }),
+        guard(propertyType, (name) =>
+          create("span", {
+            style: { opacity: "0.6" },
+            children: ` ${propertyType}`,
+          })
+        ),
+        guard(getQualifierMessage(schema.discriminator as any), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(propertyDescription, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          children: Object.keys(mapping!).map((key, index) => {
+            if (mapping[key].allOf !== undefined) {
+              const { mergedSchemas }: { mergedSchemas: SchemaObject } =
+                mergeAllOf(mapping[key].allOf);
+              // Cleanup duplicate property from mapping schema
+              delete mergedSchemas.properties![propertyName!];
+              mapping[key] = mergedSchemas;
+            }
+
+            if (mapping[key].properties !== undefined) {
+              // Cleanup duplicate property from mapping schema
+              delete mapping[key].properties![propertyName!];
+            }
+
+            const label = key;
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [
+                create("div", {
+                  style: { marginLeft: "-4px" },
+                  children: createNodes(mapping[key]),
+                }),
+              ],
+            });
+          }),
+        }),
+      ],
+    }),
+  });
+}
+
 function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: any
+  required: string[] | boolean
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -296,7 +406,7 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
-              guard(required, () => [
+              guard(schema.required && schema.required === true, () => [
                 create("strong", {
                   style: {
                     fontSize: "var(--ifm-code-font-size)",
@@ -331,18 +441,111 @@ function createDetailsNode(
   });
 }
 
+/**
+ * For handling discriminators that map to a same-level property (like 'petType').
+ * Note: These should only be encountered while iterating through properties.
+ */
+function createPropertyDiscriminator(
+  name: string,
+  schemaName: string,
+  schema: SchemaObject,
+  discriminator: any,
+  required: string[] | boolean
+): any {
+  if (schema === undefined) {
+    return undefined;
+  }
+
+  if (discriminator.mapping === undefined) {
+    return undefined;
+  }
+
+  return create("div", {
+    className: "discriminatorItem",
+    children: create("div", {
+      children: [
+        create("strong", { style: { paddingLeft: "1rem" }, children: name }),
+        guard(schemaName, (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",
+          }),
+        ]),
+        guard(getQualifierMessage(discriminator), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(schema.description, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          children: Object.keys(discriminator?.mapping!).map((key, index) => {
+            const label = key;
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [
+                create("div", {
+                  style: { marginLeft: "-4px" },
+                  children: createNodes(discriminator?.mapping[key]),
+                }),
+              ],
+            });
+          }),
+        }),
+      ],
+    }),
+  });
+}
+
 interface EdgeProps {
   name: string;
   schema: SchemaObject;
-  required: boolean;
+  required: string[] | boolean;
+  discriminator?: any | unknown;
 }
 
 /**
  * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
  */
-function createEdges({ name, schema, required }: EdgeProps): any {
+function createEdges({
+  name,
+  schema,
+  required,
+  discriminator,
+}: EdgeProps): any {
   const schemaName = getSchemaName(schema);
 
+  // if (name === "id") console.log(name, schema, required);
+
+  if (discriminator !== undefined && discriminator.propertyName === name) {
+    return createPropertyDiscriminator(
+      name,
+      "string",
+      schema,
+      discriminator,
+      required
+    );
+  }
+
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
     return createDetailsNode(name, schemaName, schema, required);
   }
@@ -351,9 +554,8 @@ function createEdges({ name, schema, required }: EdgeProps): any {
     const {
       mergedSchemas,
       required,
-    }: { mergedSchemas: SchemaObject; required: any } = mergeAllOf(
-      schema.allOf
-    );
+    }: { mergedSchemas: SchemaObject; required: string[] | boolean } =
+      mergeAllOf(schema.allOf);
     const mergedSchemaName = getSchemaName(mergedSchemas);
 
     if (
@@ -371,13 +573,23 @@ function createEdges({ name, schema, required }: EdgeProps): any {
       return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
     }
 
+    // array of objects
+    if (mergedSchemas.items?.properties !== undefined) {
+      return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
+    }
+
+    if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+      return undefined;
+    }
+
     return create("SchemaItem", {
       collapsible: false,
       name,
-      required,
+      required: false,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
+      defaultValue: mergedSchemas.default,
     });
   }
 
@@ -394,14 +606,19 @@ function createEdges({ name, schema, required }: EdgeProps): any {
     return createDetailsNode(name, schemaName, schema, required);
   }
 
+  if (schema.writeOnly && schema.writeOnly === true) {
+    return undefined;
+  }
+
   // primitives and array of non-objects
   return create("SchemaItem", {
     collapsible: false,
     name,
-    required,
+    required: false,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),
+    defaultValue: schema.default,
   });
 }
 
@@ -409,6 +626,10 @@ function createEdges({ name, schema, required }: EdgeProps): any {
  * 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.discriminator !== undefined) {
+    return createDiscriminator(schema);
+  }
+
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
     return createAnyOneOf(schema);
   }
@@ -477,11 +698,11 @@ interface Props {
       [key: string]: MediaTypeObject;
     };
     description?: string;
-    required?: boolean;
+    required?: string[] | boolean;
   };
 }
 
-export function createSchemaDetails({ title, body, ...rest }: Props) {
+export function createResponseSchema({ title, body, ...rest }: Props) {
   if (
     body === undefined ||
     body.content === undefined ||
@@ -491,8 +712,75 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
     return undefined;
   }
 
-  // NOTE: We just pick a random content-type.
-  // How common is it to have multiple?
+  // Get all MIME types, including vendor-specific
+  const mimeTypes = Object.keys(body.content);
+
+  if (mimeTypes && mimeTypes.length > 1) {
+    return create("MimeTabs", {
+      groupId: "mime-type",
+      children: mimeTypes.map((mimeType) => {
+        const firstBody = body.content![mimeType].schema;
+        if (firstBody === undefined) {
+          return undefined;
+        }
+        if (firstBody.properties !== undefined) {
+          if (Object.keys(firstBody.properties).length === 0) {
+            return undefined;
+          }
+        }
+        return create("TabItem", {
+          label: mimeType,
+          value: `${mimeType}`,
+          children: [
+            createDetails({
+              "data-collapsed": false,
+              open: true,
+              ...rest,
+              children: [
+                createDetailsSummary({
+                  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: {
+                          fontSize: "var(--ifm-code-font-size)",
+                          color: "var(--openapi-required)",
+                        },
+                        children: " required",
+                      }),
+                    ]),
+                  ],
+                }),
+                create("div", {
+                  style: { textAlign: "left", marginLeft: "1rem" },
+                  children: [
+                    guard(body.description, () => [
+                      create("div", {
+                        style: { marginTop: "1rem", marginBottom: "1rem" },
+                        children: createDescription(body.description),
+                      }),
+                    ]),
+                  ],
+                }),
+                create("ul", {
+                  style: { marginLeft: "1rem" },
+                  children: createNodes(firstBody),
+                }),
+              ],
+            }),
+          ],
+        });
+      }),
+    });
+  }
+
   const randomFirstKey = Object.keys(body.content)[0];
   const firstBody = body.content[randomFirstKey].schema;
 
@@ -506,49 +794,57 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
       return undefined;
     }
   }
-
-  // Root-level schema dropdown
-  return createDetails({
-    "data-collapsed": false,
-    open: true,
-    ...rest,
+  return create("MimeTabs", {
     children: [
-      createDetailsSummary({
-        style: { textAlign: "left" },
+      create("TabItem", {
+        label: randomFirstKey,
+        value: `${randomFirstKey}-schema`,
         children: [
-          create("strong", { children: `${title}` }),
-          guard(firstBody.type === "array", (format) =>
-            create("span", {
-              style: { opacity: "0.6" },
-              children: ` array`,
-            })
-          ),
-          guard(body.required, () => [
-            create("strong", {
-              style: {
-                fontSize: "var(--ifm-code-font-size)",
-                color: "var(--openapi-required)",
-              },
-              children: " required",
-            }),
-          ]),
-        ],
-      }),
-      create("div", {
-        style: { textAlign: "left", marginLeft: "1rem" },
-        children: [
-          guard(body.description, () => [
-            create("div", {
-              style: { marginTop: "1rem", marginBottom: "1rem" },
-              children: createDescription(body.description),
-            }),
-          ]),
+          createDetails({
+            "data-collapsed": false,
+            open: true,
+            ...rest,
+            children: [
+              createDetailsSummary({
+                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: {
+                        fontSize: "var(--ifm-code-font-size)",
+                        color: "var(--openapi-required)",
+                      },
+                      children: " required",
+                    }),
+                  ]),
+                ],
+              }),
+              create("div", {
+                style: { textAlign: "left", marginLeft: "1rem" },
+                children: [
+                  guard(body.description, () => [
+                    create("div", {
+                      style: { marginTop: "1rem", marginBottom: "1rem" },
+                      children: createDescription(body.description),
+                    }),
+                  ]),
+                ],
+              }),
+              create("ul", {
+                style: { marginLeft: "1rem" },
+                children: createNodes(firstBody),
+              }),
+            ],
+          }),
         ],
       }),
-      create("ul", {
-        style: { marginLeft: "1rem" },
-        children: createNodes(firstBody),
-      }),
     ],
   });
 }