docusaurus-plugin-openapi-docs 0.0.0-348 → 0.0.0-351

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import type { LoadContext, Plugin } from "@docusaurus/types";
+import type { PluginOptions, LoadedContent } from "./types";
+export default function pluginOpenAPI(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;

package/lib/index.js

@@ -0,0 +1,194 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const utils_1 = require("@docusaurus/utils");
+const chalk_1 = __importDefault(require("chalk"));
+const mustache_1 = require("mustache");
+const markdown_1 = require("./markdown");
+const openapi_1 = require("./openapi");
+const sidebars_1 = __importDefault(require("./sidebars"));
+function pluginOpenAPI(context, options) {
+    let { config } = options;
+    let { siteDir } = context;
+    async function generateApiDocs(options) {
+        let { specPath, outputDir, template, sidebarOptions } = options;
+        const contentPath = path_1.default.resolve(siteDir, specPath);
+        try {
+            const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, {});
+            const loadedApi = await (0, openapi_1.processOpenapiFiles)(openapiFiles);
+            if (!fs_1.default.existsSync(outputDir)) {
+                try {
+                    fs_1.default.mkdirSync(outputDir, { recursive: true });
+                    console.log(chalk_1.default.green(`Successfully created "${outputDir}"`));
+                }
+                catch (err) {
+                    console.error(chalk_1.default.red(`Failed to create "${outputDir}"`), chalk_1.default.yellow(err));
+                }
+            }
+            // TODO: figure out better way to set default
+            if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, // TODO: find a better way to handle null
+                options, loadedApi);
+                const sidebarSliceTemplate = template
+                    ? fs_1.default.readFileSync(template).toString()
+                    : `module.exports = {{{slice}}};`;
+                const view = (0, mustache_1.render)(sidebarSliceTemplate, {
+                    slice: JSON.stringify(sidebarSlice),
+                });
+                if (!fs_1.default.existsSync(`${outputDir}/sidebar.js`)) {
+                    try {
+                        fs_1.default.writeFileSync(`${outputDir}/sidebar.js`, view, "utf8");
+                        console.log(chalk_1.default.green(`Successfully created "${outputDir}/sidebar.js"`));
+                    }
+                    catch (err) {
+                        console.error(chalk_1.default.red(`Failed to write "${outputDir}/sidebar.js"`), chalk_1.default.yellow(err));
+                    }
+                }
+            }
+            const mdTemplate = template
+                ? fs_1.default.readFileSync(template).toString()
+                : `---
+id: {{{id}}}
+sidebar_label: {{{title}}}
+{{^api}}
+sidebar_position: 0
+{{/api}}
+hide_title: true
+{{#api}}
+hide_table_of_contents: true
+{{/api}}
+{{#json}}
+api: {{{json}}}
+{{/json}}
+{{#api.method}}
+sidebar_class_name: "{{{api.method}}} api-method"
+{{/api.method}}
+---
+
+{{{markdown}}}
+      `;
+            loadedApi.map(async (item) => {
+                const markdown = item.type === "api" ? (0, markdown_1.createApiPageMD)(item) : (0, markdown_1.createInfoPageMD)(item);
+                item.markdown = markdown;
+                if (item.type === "api") {
+                    item.json = JSON.stringify(item.api);
+                }
+                const view = (0, mustache_1.render)(mdTemplate, item);
+                if (item.type === "api") {
+                    if (!fs_1.default.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
+                        try {
+                            fs_1.default.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
+                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.api.mdx"`));
+                        }
+                        catch (err) {
+                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/${item.id}.api.mdx"`), chalk_1.default.yellow(err));
+                        }
+                    }
+                }
+                // TODO: determine if we actually want/need this
+                if (item.type === "info") {
+                    if (!fs_1.default.existsSync(`${outputDir}/index.api.mdx`)) {
+                        try {
+                            fs_1.default.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
+                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/index.api.mdx"`));
+                        }
+                        catch (err) {
+                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/index.api.mdx"`), chalk_1.default.yellow(err));
+                        }
+                    }
+                }
+                return;
+            });
+            return;
+        }
+        catch (e) {
+            console.error(chalk_1.default.red(`Loading of api failed for "${contentPath}"`));
+            throw e;
+        }
+    }
+    async function cleanApiDocs(options) {
+        const { outputDir } = options;
+        const apiDir = path_1.default.join(siteDir, outputDir);
+        const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx"], {
+            cwd: path_1.default.resolve(apiDir),
+        });
+        const sidebarFile = await (0, utils_1.Globby)(["sidebar.js"], {
+            cwd: path_1.default.resolve(apiDir),
+        });
+        apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
+            if (err) {
+                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${mdx}"`), chalk_1.default.yellow(err));
+            }
+            else {
+                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
+            }
+        }));
+        sidebarFile.map((sidebar) => fs_1.default.unlink(`${apiDir}/${sidebar}`, (err) => {
+            if (err) {
+                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${sidebar}"`), chalk_1.default.yellow(err));
+            }
+            else {
+                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`));
+            }
+        }));
+    }
+    return {
+        name: `docusaurus-plugin-openapi`,
+        extendCli(cli) {
+            cli
+                .command(`gen-api-docs`)
+                .description(`Generates API Docs mdx and sidebars.`)
+                .usage("[options] <id key value in plugin config within docusaurus.config.js>")
+                .arguments("<id>")
+                .action(async (id) => {
+                if (id === "all") {
+                    if (config[id]) {
+                        console.error(chalk_1.default.red("Can't use id 'all' for API Doc."));
+                    }
+                    else {
+                        Object.keys(config).forEach(async function (key) {
+                            await generateApiDocs(config[key]);
+                        });
+                    }
+                }
+                else if (!config[id]) {
+                    console.error(chalk_1.default.red(`ID ${id} does not exist in openapi-plugin config`));
+                }
+                else {
+                    await generateApiDocs(config[id]);
+                }
+            });
+            cli
+                .command(`clean-api-docs`)
+                .description(`Clears the Generated API Docs mdx and sidebars.`)
+                .usage("[options] <id key value in plugin config within docusaurus.config.js>")
+                .arguments("<id>")
+                .action(async (id) => {
+                if (id === "all") {
+                    if (config[id]) {
+                        console.error(chalk_1.default.red("Can't use id 'all' for API Doc."));
+                    }
+                    else {
+                        Object.keys(config).forEach(async function (key) {
+                            await cleanApiDocs(config[key]);
+                        });
+                    }
+                }
+                else {
+                    await cleanApiDocs(config[id]);
+                }
+            });
+        },
+    };
+}
+exports.default = pluginOpenAPI;

package/lib/markdown/createContactInfo.d.ts

@@ -0,0 +1,2 @@
+import { ContactObject } from "../openapi/types";
+export declare function createContactInfo(contact: ContactObject): string;

package/lib/markdown/createContactInfo.js

@@ -0,0 +1,49 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContactInfo = void 0;
+const utils_1 = require("./utils");
+function createContactInfo(contact) {
+    if (!contact)
+        return "";
+    const { name, url, email } = contact;
+    return (0, utils_1.create)("div", {
+        style: {
+            display: "flex",
+            flexDirection: "column",
+            marginBottom: "var(--ifm-paragraph-margin-bottom)",
+        },
+        children: [
+            (0, utils_1.create)("h3", {
+                style: {
+                    marginBottom: "0.25rem",
+                },
+                children: "Contact",
+            }),
+            (0, utils_1.create)("span", {
+                children: [
+                    `${name}: `,
+                    (0, utils_1.create)("a", {
+                        href: `mailto:${email}`,
+                        children: `${email}`,
+                    }),
+                ],
+            }),
+            (0, utils_1.create)("span", {
+                children: [
+                    "URL: ",
+                    (0, utils_1.create)("a", {
+                        href: `${url}`,
+                        children: `${url}`,
+                    }),
+                ],
+            }),
+        ],
+    });
+}
+exports.createContactInfo = createContactInfo;

package/lib/markdown/createDeprecationNotice.d.ts

@@ -0,0 +1,6 @@
+interface DeprecationNoticeProps {
+    deprecated?: boolean;
+    description?: string;
+}
+export declare function createDeprecationNotice({ deprecated, description, }: DeprecationNoticeProps): string;
+export {};

package/lib/markdown/createDeprecationNotice.js

@@ -0,0 +1,19 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeprecationNotice = void 0;
+const utils_1 = require("./utils");
+function createAdmonition({ children }) {
+    return `:::caution deprecated\n\n${(0, utils_1.render)(children)}\n\n:::`;
+}
+function createDeprecationNotice({ deprecated, description, }) {
+    return (0, utils_1.guard)(deprecated, () => createAdmonition({
+        children: description !== null && description !== void 0 ? description : "This endpoint has been deprecated and may be removed in future versions of the API.",
+    }));
+}
+exports.createDeprecationNotice = createDeprecationNotice;

package/lib/markdown/createDescription.d.ts

@@ -0,0 +1 @@
+export declare function createDescription(description: string | undefined): string;

package/lib/markdown/createDescription.js

@@ -0,0 +1,16 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDescription = void 0;
+function createDescription(description) {
+    if (!description) {
+        return "";
+    }
+    return `\n\n${description}\n\n`;
+}
+exports.createDescription = createDescription;

package/lib/markdown/createDetails.d.ts

@@ -0,0 +1,2 @@
+import { Props } from "./utils";
+export declare function createDetails({ children, style, ...rest }: Props): string;

package/lib/markdown/createDetails.js

@@ -0,0 +1,18 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDetails = void 0;
+const utils_1 = require("./utils");
+function createDetails({ children, style, ...rest }) {
+    return (0, utils_1.create)("details", {
+        style: { ...style },
+        ...rest,
+        children,
+    });
+}
+exports.createDetails = createDetails;

package/lib/markdown/createDetailsSummary.d.ts

@@ -0,0 +1,2 @@
+import { Props } from "./utils";
+export declare function createDetailsSummary({ children, style, ...rest }: Props): string;

package/lib/markdown/createDetailsSummary.js

@@ -0,0 +1,18 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDetailsSummary = void 0;
+const utils_1 = require("./utils");
+function createDetailsSummary({ children, style, ...rest }) {
+    return (0, utils_1.create)("summary", {
+        style: { ...style },
+        ...rest,
+        children,
+    });
+}
+exports.createDetailsSummary = createDetailsSummary;

package/lib/markdown/createLicense.d.ts

@@ -0,0 +1,2 @@
+import { LicenseObject } from "../openapi/types";
+export declare function createLicense(license: LicenseObject): string;

package/lib/markdown/createLicense.js

@@ -0,0 +1,33 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLicense = void 0;
+const utils_1 = require("./utils");
+function createLicense(license) {
+    if (!license)
+        return "";
+    const { name, url } = license;
+    return (0, utils_1.create)("div", {
+        style: {
+            marginBottom: "var(--ifm-paragraph-margin-bottom)",
+        },
+        children: [
+            (0, utils_1.create)("h3", {
+                style: {
+                    marginBottom: "0.25rem",
+                },
+                children: "License",
+            }),
+            (0, utils_1.create)("a", {
+                href: url,
+                children: name,
+            }),
+        ],
+    });
+}
+exports.createLicense = createLicense;

package/lib/markdown/createParamsDetails.d.ts

@@ -0,0 +1,7 @@
+import { ApiItem } from "../types";
+interface Props {
+    parameters: ApiItem["parameters"];
+    type: "path" | "query" | "header" | "cookie";
+}
+export declare function createParamsDetails({ parameters, type }: Props): string | undefined;
+export {};

package/lib/markdown/createParamsDetails.js

@@ -0,0 +1,44 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createParamsDetails = void 0;
+const createDetails_1 = require("./createDetails");
+const createDetailsSummary_1 = require("./createDetailsSummary");
+const utils_1 = require("./utils");
+function createParamsDetails({ parameters, type }) {
+    if (parameters === undefined) {
+        return undefined;
+    }
+    const params = parameters.filter((param) => (param === null || param === void 0 ? void 0 : param.in) === type);
+    if (params.length === 0) {
+        return undefined;
+    }
+    return (0, createDetails_1.createDetails)({
+        style: { marginBottom: "1rem" },
+        children: [
+            (0, createDetailsSummary_1.createDetailsSummary)({
+                children: [
+                    (0, utils_1.create)("strong", {
+                        children: `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`,
+                    }),
+                ],
+            }),
+            (0, utils_1.create)("div", {
+                children: [
+                    (0, utils_1.create)("ul", {
+                        children: params.map((param) => (0, utils_1.create)("ParamsItem", {
+                            className: "paramsItem",
+                            param: param,
+                        })),
+                    }),
+                ],
+            }),
+        ],
+    });
+}
+exports.createParamsDetails = createParamsDetails;

package/lib/markdown/createRequestBodyDetails.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    title: string;
+    body: any;
+}
+export declare function createRequestBodyDetails({ title, body }: Props): string | undefined;
+export {};

package/lib/markdown/createRequestBodyDetails.js

@@ -0,0 +1,14 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestBodyDetails = void 0;
+const createSchemaDetails_1 = require("./createSchemaDetails");
+function createRequestBodyDetails({ title, body }) {
+    return (0, createSchemaDetails_1.createSchemaDetails)({ title, body });
+}
+exports.createRequestBodyDetails = createRequestBodyDetails;

package/lib/markdown/createSchemaDetails.d.ts

@@ -0,0 +1,14 @@
+import { MediaTypeObject } from "../openapi/types";
+interface Props {
+    style?: any;
+    title: string;
+    body: {
+        content?: {
+            [key: string]: MediaTypeObject;
+        };
+        description?: string;
+        required?: boolean;
+    };
+}
+export declare function createSchemaDetails({ title, body, ...rest }: Props): string | undefined;
+export {};