docusaurus-plugin-openapi-docs 1.7.2 → 1.7.3

package/src/markdown/createResponseSchema.ts

@@ -58,7 +58,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
  */
 function createAnyOneOf(schema: SchemaObject): any {
   const type = schema.oneOf ? "oneOf" : "anyOf";
-  return create("li", {
+  return create("div", {
     children: [
       create("span", {
         className: "badge badge--info",
@@ -73,14 +73,17 @@ function createAnyOneOf(schema: SchemaObject): any {
 
           if (anyOneSchema.properties !== undefined) {
             anyOneChildren.push(createProperties(anyOneSchema));
+            delete anyOneSchema.properties;
           }
 
           if (anyOneSchema.allOf !== undefined) {
             anyOneChildren.push(createNodes(anyOneSchema));
+            delete anyOneSchema.allOf;
           }
 
           if (anyOneSchema.items !== undefined) {
             anyOneChildren.push(createItems(anyOneSchema));
+            delete anyOneSchema.items;
           }
 
           if (
@@ -165,6 +168,18 @@ function createAdditionalProperties(schema: SchemaObject) {
   // }
   const additionalProperties = schema.additionalProperties;
   const type: string | unknown = additionalProperties?.type;
+  // Handle free-form objects
+  if (String(additionalProperties) === "true" && schema.type === "object") {
+    return create("SchemaItem", {
+      name: "property name*",
+      required: false,
+      schemaName: "any",
+      qualifierMessage: getQualifierMessage(schema.additionalProperties),
+      schema: schema,
+      collapsible: false,
+      discriminator: false,
+    });
+  }
   if (
     (type === "object" || type === "array") &&
     (additionalProperties?.properties ||
@@ -174,12 +189,12 @@ function createAdditionalProperties(schema: SchemaObject) {
       additionalProperties?.oneOf ||
       additionalProperties?.anyOf)
   ) {
-    const title = additionalProperties.title;
-    const schemaName = title ? `object (${title})` : "object";
+    const title = additionalProperties.title as string;
+    const schemaName = getSchemaName(additionalProperties);
     const required = schema.required ?? false;
     return createDetailsNode(
       "property name*",
-      schemaName,
+      title ?? schemaName,
       additionalProperties,
       required,
       schema.nullable
@@ -197,51 +212,30 @@ function createAdditionalProperties(schema: SchemaObject) {
       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: [
-            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),
-              })
-            ),
-          ],
-        }),
+      const schemaName = getSchemaName(
+        schema.additionalProperties?.additionalProperties!
+      );
+      return create("SchemaItem", {
+        name: "property name*",
+        required: false,
+        schemaName: schemaName ?? type,
+        qualifierMessage:
+          schema.additionalProperties ??
+          getQualifierMessage(schema.additionalProperties),
+        schema: schema,
+        collapsible: false,
+        discriminator: false,
       });
     }
-    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),
-            })
-          ),
-        ],
-      }),
+    const schemaName = getSchemaName(schema.additionalProperties!);
+    return create("SchemaItem", {
+      name: "property name*",
+      required: false,
+      schemaName: schemaName,
+      qualifierMessage: getQualifierMessage(schema),
+      schema: schema.additionalProperties,
+      collapsible: false,
+      discriminator: false,
     });
   }
   return Object.entries(schema.additionalProperties!).map(([key, val]) =>
@@ -532,6 +526,104 @@ function createDetailsNode(
   });
 }
 
+function createOneOfProperty(
+  name: string,
+  schemaName: string,
+  schema: SchemaObject,
+  required: string[] | boolean,
+  nullable: boolean | unknown
+): any {
+  return create("SchemaItem", {
+    collapsible: true,
+    className: "schemaItem",
+    children: [
+      createDetails({
+        children: [
+          createDetailsSummary({
+            children: [
+              create("strong", { children: name }),
+              create("span", {
+                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)
+                  : required === true,
+                () => [
+                  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),
+                })
+              ),
+            ],
+          }),
+          create("div", {
+            children: [
+              create("span", {
+                className: "badge badge--info",
+                children: "oneOf",
+              }),
+              create("SchemaTabs", {
+                children: schema["oneOf"]!.map((property, index) => {
+                  const label = property.type ?? `MOD${index + 1}`;
+                  return create("TabItem", {
+                    label: label,
+                    value: `${index}-property`,
+                    children: [
+                      create("p", { children: label }),
+                      guard(schema.description, (description) =>
+                        create("div", {
+                          style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                          children: createDescription(description),
+                        })
+                      ),
+                    ],
+                  });
+                }),
+              }),
+            ],
+          }),
+        ],
+      }),
+    ],
+  });
+}
+
 /**
  * For handling discriminators that map to a same-level property (like 'petType').
  * Note: These should only be encountered while iterating through properties.
@@ -542,7 +634,7 @@ function createPropertyDiscriminator(
   schema: SchemaObject,
   discriminator: any,
   required: string[] | boolean
-): any {
+) {
   if (schema === undefined) {
     return undefined;
   }
@@ -551,59 +643,26 @@ function createPropertyDiscriminator(
     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]),
-                }),
-              ],
-            });
-          }),
+  return create("SchemaItem", {
+    name,
+    required: Array.isArray(required) ? required.includes(name) : required,
+    schemaName: schemaName,
+    qualifierMessage: getQualifierMessage(schema),
+    schema: schema,
+    collapsible: false,
+    discriminator: true,
+    children: [
+      create("DiscriminatorTabs", {
+        children: Object.keys(discriminator?.mapping!).map((key, index) => {
+          const label = key;
+          return create("TabItem", {
+            label: label,
+            value: `${index}-item-discriminator`,
+            children: createNodes(discriminator?.mapping[key]),
+          });
         }),
-      ],
-    }),
+      }),
+    ],
   });
 }
 
@@ -636,7 +695,7 @@ function createEdges({
   }
 
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
-    return createDetailsNode(
+    return createOneOfProperty(
       name,
       schemaName,
       schema,
@@ -810,30 +869,38 @@ function createNodes(schema: SchemaObject): any {
 
   // primitive
   if (schema.type !== undefined) {
-    return create("li", {
-      children: create("div", {
-        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),
-            })
-          ),
-        ],
-      }),
+    if (schema.allOf) {
+      //handle circular result in allOf
+      if (schema.allOf.length && typeof schema.allOf[0] === "string") {
+        return create("div", {
+          style: {
+            marginTop: ".5rem",
+            marginBottom: ".5rem",
+            marginLeft: "1rem",
+          },
+          children: createDescription(schema.allOf[0]),
+        });
+      }
+    }
+    return create("div", {
+      style: {
+        marginTop: ".5rem",
+        marginBottom: ".5rem",
+        marginLeft: "1rem",
+      },
+      children: createDescription(schema.type),
+    });
+  }
+
+  // handle circular references
+  if (typeof schema === "string") {
+    return create("div", {
+      style: {
+        marginTop: ".5rem",
+        marginBottom: ".5rem",
+        marginLeft: "1rem",
+      },
+      children: [createDescription(schema)],
     });
   }
 

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -101,7 +101,16 @@ async function resolveJsonRefs(specUrlOrObject: object | string) {
     });
     return schema as OpenApiObject;
   } catch (err: any) {
-    console.error(chalk.yellow(err.errors[0]?.message ?? err));
+    let errorMsg = "";
+
+    if (err.errors[0] !== undefined) {
+      const error = err.errors[0];
+      errorMsg = `Error: [${error.message}] with footprint [${error.footprint}]`;
+    } else {
+      errorMsg = err;
+    }
+
+    console.error(chalk.yellow(errorMsg));
     return;
   }
 }

package/src/options.ts

@@ -16,6 +16,12 @@ const sidebarOptions = Joi.object({
   sidebarCollapsed: Joi.boolean(),
 });
 
+const markdownGenerators = Joi.object({
+  createApiPageMD: Joi.function(),
+  createInfoPageMD: Joi.function(),
+  createTagPageMD: Joi.function(),
+});
+
 export const OptionsSchema = Joi.object({
   id: Joi.string().required(),
   docsPluginId: Joi.string().required(),
@@ -31,6 +37,7 @@ export const OptionsSchema = Joi.object({
         hideSendButton: Joi.boolean(),
         showExtensions: Joi.boolean(),
         sidebarOptions: sidebarOptions,
+        markdownGenerators: markdownGenerators,
         version: Joi.string().when("versions", {
           is: Joi.exist(),
           then: Joi.required(),

package/src/types.ts

@@ -43,6 +43,13 @@ export interface APIOptions {
     [key: string]: APIVersionOptions;
   };
   proxy?: string;
+  markdownGenerators?: MarkdownGenerator;
+}
+
+export interface MarkdownGenerator {
+  createApiPageMD?: (pageData: ApiPageMetadata) => string;
+  createInfoPageMD?: (pageData: InfoPageMetadata) => string;
+  createTagPageMD?: (pageData: TagPageMetadata) => string;
 }
 
 export interface SidebarOptions {