docusaurus-plugin-openapi-docs 1.7.2 → 1.7.3

package/lib/markdown/createResponseSchema.js

@@ -48,7 +48,7 @@ exports.mergeAllOf = mergeAllOf;
  */
 function createAnyOneOf(schema) {
     const type = schema.oneOf ? "oneOf" : "anyOf";
-    return (0, utils_1.create)("li", {
+    return (0, utils_1.create)("div", {
         children: [
             (0, utils_1.create)("span", {
                 className: "badge badge--info",
@@ -62,12 +62,15 @@ function createAnyOneOf(schema) {
                     const anyOneChildren = [];
                     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 (anyOneSchema.type === "string" ||
                         anyOneSchema.type === "number" ||
@@ -145,6 +148,18 @@ function createAdditionalProperties(schema) {
     // }
     const additionalProperties = schema.additionalProperties;
     const type = additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.type;
+    // Handle free-form objects
+    if (String(additionalProperties) === "true" && schema.type === "object") {
+        return (0, utils_1.create)("SchemaItem", {
+            name: "property name*",
+            required: false,
+            schemaName: "any",
+            qualifierMessage: (0, schema_1.getQualifierMessage)(schema.additionalProperties),
+            schema: schema,
+            collapsible: false,
+            discriminator: false,
+        });
+    }
     if ((type === "object" || type === "array") &&
         ((additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.properties) ||
             (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.items) ||
@@ -153,9 +168,9 @@ function createAdditionalProperties(schema) {
             (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.oneOf) ||
             (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.anyOf))) {
         const title = additionalProperties.title;
-        const schemaName = title ? `object (${title})` : "object";
+        const schemaName = (0, schema_1.getSchemaName)(additionalProperties);
         const required = (_a = schema.required) !== null && _a !== void 0 ? _a : false;
-        return createDetailsNode("property name*", schemaName, additionalProperties, required, schema.nullable);
+        return createDetailsNode("property name*", title !== null && title !== void 0 ? title : schemaName, additionalProperties, required, schema.nullable);
     }
     if (((_b = schema.additionalProperties) === null || _b === void 0 ? void 0 : _b.type) === "string" ||
         ((_c = schema.additionalProperties) === null || _c === void 0 ? void 0 : _c.type) === "object" ||
@@ -165,41 +180,26 @@ function createAdditionalProperties(schema) {
         const additionalProperties = (_g = schema.additionalProperties) === null || _g === void 0 ? void 0 : _g.additionalProperties;
         if (additionalProperties !== undefined) {
             const type = (_j = (_h = schema.additionalProperties) === null || _h === void 0 ? void 0 : _h.additionalProperties) === null || _j === void 0 ? void 0 : _j.type;
-            const format = (_l = (_k = schema.additionalProperties) === null || _k === void 0 ? void 0 : _k.additionalProperties) === null || _l === void 0 ? void 0 : _l.format;
-            return (0, utils_1.create)("li", {
-                children: (0, utils_1.create)("div", {
-                    children: [
-                        (0, utils_1.create)("code", { children: `property name*` }),
-                        (0, utils_1.guard)(type, (type) => (0, utils_1.create)("span", {
-                            style: { opacity: "0.6" },
-                            children: ` ${type}`,
-                        })),
-                        (0, utils_1.guard)(format, (format) => (0, utils_1.create)("span", {
-                            style: { opacity: "0.6" },
-                            children: ` (${format})`,
-                        })),
-                        (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema.additionalProperties), (message) => (0, utils_1.create)("div", {
-                            style: { marginTop: "var(--ifm-table-cell-padding)" },
-                            children: (0, createDescription_1.createDescription)(message),
-                        })),
-                    ],
-                }),
+            const schemaName = (0, schema_1.getSchemaName)((_k = schema.additionalProperties) === null || _k === void 0 ? void 0 : _k.additionalProperties);
+            return (0, utils_1.create)("SchemaItem", {
+                name: "property name*",
+                required: false,
+                schemaName: schemaName !== null && schemaName !== void 0 ? schemaName : type,
+                qualifierMessage: (_l = schema.additionalProperties) !== null && _l !== void 0 ? _l : (0, schema_1.getQualifierMessage)(schema.additionalProperties),
+                schema: schema,
+                collapsible: false,
+                discriminator: false,
             });
         }
-        return (0, utils_1.create)("li", {
-            children: (0, utils_1.create)("div", {
-                children: [
-                    (0, utils_1.create)("code", { children: `property name*` }),
-                    (0, utils_1.guard)(type, (type) => (0, utils_1.create)("span", {
-                        style: { opacity: "0.6" },
-                        children: ` ${type}`,
-                    })),
-                    (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema.additionalProperties), (message) => (0, utils_1.create)("div", {
-                        style: { marginTop: "var(--ifm-table-cell-padding)" },
-                        children: (0, createDescription_1.createDescription)(message),
-                    })),
-                ],
-            }),
+        const schemaName = (0, schema_1.getSchemaName)(schema.additionalProperties);
+        return (0, utils_1.create)("SchemaItem", {
+            name: "property name*",
+            required: false,
+            schemaName: schemaName,
+            qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
+            schema: schema.additionalProperties,
+            collapsible: false,
+            discriminator: false,
         });
     }
     return Object.entries(schema.additionalProperties).map(([key, val]) => createEdges({
@@ -443,6 +443,86 @@ function createDetailsNode(name, schemaName, schema, required, nullable) {
         ],
     });
 }
+function createOneOfProperty(name, schemaName, schema, required, nullable) {
+    return (0, utils_1.create)("SchemaItem", {
+        collapsible: true,
+        className: "schemaItem",
+        children: [
+            (0, createDetails_1.createDetails)({
+                children: [
+                    (0, createDetailsSummary_1.createDetailsSummary)({
+                        children: [
+                            (0, utils_1.create)("strong", { children: name }),
+                            (0, utils_1.create)("span", {
+                                style: { opacity: "0.6" },
+                                children: ` ${schemaName}`,
+                            }),
+                            (0, utils_1.guard)((schema.nullable && schema.nullable === true) ||
+                                (nullable && nullable === true), () => [
+                                (0, utils_1.create)("strong", {
+                                    style: {
+                                        fontSize: "var(--ifm-code-font-size)",
+                                        color: "var(--openapi-nullable)",
+                                    },
+                                    children: " nullable",
+                                }),
+                            ]),
+                            (0, utils_1.guard)(Array.isArray(required)
+                                ? required.includes(name)
+                                : required === true, () => [
+                                (0, utils_1.create)("strong", {
+                                    style: {
+                                        fontSize: "var(--ifm-code-font-size)",
+                                        color: "var(--openapi-required)",
+                                    },
+                                    children: " required",
+                                }),
+                            ]),
+                        ],
+                    }),
+                    (0, utils_1.create)("div", {
+                        style: { marginLeft: "1rem" },
+                        children: [
+                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
+                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                children: (0, createDescription_1.createDescription)(message),
+                            })),
+                            (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                children: (0, createDescription_1.createDescription)(description),
+                            })),
+                        ],
+                    }),
+                    (0, utils_1.create)("div", {
+                        children: [
+                            (0, utils_1.create)("span", {
+                                className: "badge badge--info",
+                                children: "oneOf",
+                            }),
+                            (0, utils_1.create)("SchemaTabs", {
+                                children: schema["oneOf"].map((property, index) => {
+                                    var _a;
+                                    const label = (_a = property.type) !== null && _a !== void 0 ? _a : `MOD${index + 1}`;
+                                    return (0, utils_1.create)("TabItem", {
+                                        label: label,
+                                        value: `${index}-property`,
+                                        children: [
+                                            (0, utils_1.create)("p", { children: label }),
+                                            (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                                children: (0, createDescription_1.createDescription)(description),
+                                            })),
+                                        ],
+                                    });
+                                }),
+                            }),
+                        ],
+                    }),
+                ],
+            }),
+        ],
+    });
+}
 /**
  * For handling discriminators that map to a same-level property (like 'petType').
  * Note: These should only be encountered while iterating through properties.
@@ -454,53 +534,26 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
     if (discriminator.mapping === undefined) {
         return undefined;
     }
-    return (0, utils_1.create)("div", {
-        className: "discriminatorItem",
-        children: (0, utils_1.create)("div", {
-            children: [
-                (0, utils_1.create)("strong", { style: { paddingLeft: "1rem" }, children: name }),
-                (0, utils_1.guard)(schemaName, (name) => (0, utils_1.create)("span", {
-                    style: { opacity: "0.6" },
-                    children: ` ${schemaName}`,
-                })),
-                (0, utils_1.guard)(required, () => [
-                    (0, utils_1.create)("strong", {
-                        style: {
-                            fontSize: "var(--ifm-code-font-size)",
-                            color: "var(--openapi-required)",
-                        },
-                        children: " required",
-                    }),
-                ]),
-                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
-                    style: {
-                        paddingLeft: "1rem",
-                    },
-                    children: (0, createDescription_1.createDescription)(message),
-                })),
-                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
-                    style: {
-                        paddingLeft: "1rem",
-                    },
-                    children: (0, createDescription_1.createDescription)(description),
-                })),
-                (0, utils_1.create)("DiscriminatorTabs", {
-                    children: Object.keys(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping).map((key, index) => {
-                        const label = key;
-                        return (0, utils_1.create)("TabItem", {
-                            label: label,
-                            value: `${index}-item-discriminator`,
-                            children: [
-                                (0, utils_1.create)("div", {
-                                    style: { marginLeft: "-4px" },
-                                    children: createNodes(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping[key]),
-                                }),
-                            ],
-                        });
-                    }),
+    return (0, utils_1.create)("SchemaItem", {
+        name,
+        required: Array.isArray(required) ? required.includes(name) : required,
+        schemaName: schemaName,
+        qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
+        schema: schema,
+        collapsible: false,
+        discriminator: true,
+        children: [
+            (0, utils_1.create)("DiscriminatorTabs", {
+                children: Object.keys(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping).map((key, index) => {
+                    const label = key;
+                    return (0, utils_1.create)("TabItem", {
+                        label: label,
+                        value: `${index}-item-discriminator`,
+                        children: createNodes(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping[key]),
+                    });
                 }),
-            ],
-        }),
+            }),
+        ],
     });
 }
 /**
@@ -513,7 +566,7 @@ function createEdges({ name, schema, required, discriminator, }) {
         return createPropertyDiscriminator(name, "string", schema, discriminator, required);
     }
     if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
-        return createDetailsNode(name, schemaName, schema, required, schema.nullable);
+        return createOneOfProperty(name, schemaName, schema, required, schema.nullable);
     }
     if (schema.allOf !== undefined) {
         const { mergedSchemas, required, } = mergeAllOf(schema.allOf);
@@ -605,24 +658,37 @@ function createNodes(schema) {
     }
     // primitive
     if (schema.type !== undefined) {
-        return (0, utils_1.create)("li", {
-            children: (0, utils_1.create)("div", {
-                children: [
-                    (0, utils_1.create)("strong", { children: schema.type }),
-                    (0, utils_1.guard)(schema.format, (format) => (0, utils_1.create)("span", {
-                        style: { opacity: "0.6" },
-                        children: ` ${format}`,
-                    })),
-                    (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
-                        style: { marginTop: "var(--ifm-table-cell-padding)" },
-                        children: (0, createDescription_1.createDescription)(message),
-                    })),
-                    (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
-                        style: { marginTop: "var(--ifm-table-cell-padding)" },
-                        children: (0, createDescription_1.createDescription)(description),
-                    })),
-                ],
-            }),
+        if (schema.allOf) {
+            //handle circular result in allOf
+            if (schema.allOf.length && typeof schema.allOf[0] === "string") {
+                return (0, utils_1.create)("div", {
+                    style: {
+                        marginTop: ".5rem",
+                        marginBottom: ".5rem",
+                        marginLeft: "1rem",
+                    },
+                    children: (0, createDescription_1.createDescription)(schema.allOf[0]),
+                });
+            }
+        }
+        return (0, utils_1.create)("div", {
+            style: {
+                marginTop: ".5rem",
+                marginBottom: ".5rem",
+                marginLeft: "1rem",
+            },
+            children: (0, createDescription_1.createDescription)(schema.type),
+        });
+    }
+    // handle circular references
+    if (typeof schema === "string") {
+        return (0, utils_1.create)("div", {
+            style: {
+                marginTop: ".5rem",
+                marginBottom: ".5rem",
+                marginLeft: "1rem",
+            },
+            children: [(0, createDescription_1.createDescription)(schema)],
         });
     }
     // Unknown node/schema type should return undefined

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -74,7 +74,6 @@ function convertSwagger2OpenAPI(spec) {
 }
 exports.convertSwagger2OpenAPI = convertSwagger2OpenAPI;
 async function resolveJsonRefs(specUrlOrObject) {
-    var _a, _b;
     try {
         let schema = await json_schema_ref_parser_1.default.dereference(specUrlOrObject, {
             continueOnError: true,
@@ -92,7 +91,15 @@ async function resolveJsonRefs(specUrlOrObject) {
         return schema;
     }
     catch (err) {
-        console.error(chalk_1.default.yellow((_b = (_a = err.errors[0]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : 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_1.default.yellow(errorMsg));
         return;
     }
 }

package/lib/options.js

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

package/lib/types.d.ts

@@ -23,6 +23,12 @@ 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 {
     groupPathsBy?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -68,5 +68,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "d6450052aff8a6fc691aef3d38bf835f4c70b1ef"
+  "gitHead": "b30ae6acf881863cb2422bce775f1d9fe6f0fcb6"
 }

package/src/index.ts

@@ -91,8 +91,14 @@ export default function pluginOpenAPIDocs(
   let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
   async function generateApiDocs(options: APIOptions, pluginId: any) {
-    let { specPath, outputDir, template, downloadUrl, sidebarOptions } =
-      options;
+    let {
+      specPath,
+      outputDir,
+      template,
+      markdownGenerators,
+      downloadUrl,
+      sidebarOptions,
+    } = options;
 
     // Remove trailing slash before proceeding
     outputDir = outputDir.replace(/\/$/, "");
@@ -237,6 +243,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 \`\`\`
       `;
 
+      const apiPageGenerator =
+        markdownGenerators?.createApiPageMD ?? createApiPageMD;
+      const infoPageGenerator =
+        markdownGenerators?.createInfoPageMD ?? createInfoPageMD;
+      const tagPageGenerator =
+        markdownGenerators?.createTagPageMD ?? createTagPageMD;
+
       loadedApi.map(async (item) => {
         if (item.type === "info") {
           if (downloadUrl && isURL(downloadUrl)) {
@@ -245,10 +258,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         }
         const markdown =
           item.type === "api"
-            ? createApiPageMD(item)
+            ? apiPageGenerator(item)
             : item.type === "info"
-            ? createInfoPageMD(item)
-            : createTagPageMD(item);
+            ? infoPageGenerator(item)
+            : tagPageGenerator(item);
         item.markdown = markdown;
         if (item.type === "api") {
           item.json = JSON.stringify(item.api);