docusaurus-plugin-openapi-docs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Palo Alto Networks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+<h1 align="center">Docusaurus OpenAPI Doc Generator</h1>
+
+<div align="center">
+<img width="200" src="https://user-images.githubusercontent.com/9343811/165975569-1bc29814-884c-4931-83df-860043b625b7.svg" />
+</div>
+
+<div align="center">
+
+OpenAPI plugin for generating API reference docs in Docusaurus v2.
+
+</div>
+
+<p align="center">
+
+<img width="650" alt="delete-a-pet" src="https://user-images.githubusercontent.com/9343811/165620346-d666db22-3587-4ddf-af58-947fddc9fe99.png">
+
+</p>
+
+## Overview
+
+The `docusaurus-plugin-openapi-docs` package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with [plugin-content-docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) and can be used to render beautiful reference API docs by setting `docItemComponent` to `@theme/ApiItem`, a custom component included in the `docusaurus-theme-openapi-docs` theme.
+
+## Installation
+
+Plugin:
+
+```bash
+yarn add docusaurus-plugin-openapi-docs
+```
+
+Theme:
+
+```bash
+yarn add docusaurus-theme-openapi-docs
+```
+
+## Configuring `docusaurus.config.js` (Plugin and theme usage)
+
+Here is an example of properly configuring your `docusaurus.config.js` file for `docusaurus-plugin-openapi-docs` and `docusaurus-theme-openapi-docs` usage.
+
+```js
+// docusaurus.config.js
+
+{
+  presets: [
+  [
+    "classic",
+    /** @type {import('@docusaurus/preset-classic').Options} */
+    ({
+      docs: {
+        sidebarPath: require.resolve("./sidebars.js"),
+        // Please change this to your repo.
+        // Remove this to remove the "edit this page" links.
+        editUrl:
+          "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
+        docLayoutComponent: "@theme/DocPage",
+        docItemComponent: "@theme/ApiItem" // Derived from docusaurus-theme-openapi-docs
+      },
+      blog: {
+        showReadingTime: true,
+        // Please change this to your repo.
+        // Remove this to remove the "edit this page" links.
+        editUrl:
+          "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
+      },
+      theme: {
+        customCss: require.resolve("./src/css/custom.css")
+      }
+    })
+  ]
+],
+
+  plugins: [
+    [
+      'docusaurus-plugin-openapi-docs',
+      {
+        id: "apiDocs",
+        config: {
+          petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
+            specPath: "examples/petstore.yaml", // Path to designated spec file
+            outputDir: "api/petstore", // Output directory for generated .mdx docs
+            sidebarOptions: {
+              groupPathsBy: "tags",
+            },
+          },
+          burgers: {
+            specPath: "examples/food/burgers/openapi.yaml",
+            outputDir: "api/food/burgers",
+          }
+        }
+      },
+    ]
+  ],
+  themes: ["docusaurus-theme-openapi-docs"] // Allows use of @theme/ApiItem and other components
+}
+```
+
+> Note: You may optionally configure a dedicated `@docusaurus/plugin-content-docs` instance for use with `docusaurus-theme-openapi-docs` by setting `docItemComponent` to `@theme/ApiItem`.
+
+### Plugin Configuration Options
+
+`docusaurus-plugin-openapi-docs` can be configured with the following options:
+
+| Name             | Type     | Default | Description                                                                                                          |
+| ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `specPath`       | `string` | `null`  | Designated path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
+| `ouputDir`       | `string` | `null`  | Desired output path for generated MDX files.                                                                         |
+| `template`       | `string` | `null`  | _Optional:_ Customize MDX content with a desired template.                                                           |
+| `sidebarOptions` | `object` | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                     |
+
+`sidebarOptions` can be configured with the following options:
+
+| Name                 | Type      | Default | Description                                                                                                                         |
+| -------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `groupPathsBy`       | `string`  | `null`  | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by "tags". |
+| `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                              |
+| `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                |
+| `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                    |
+
+> Note: You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
+
+## CLI Usage
+
+```bash
+Usage: docusaurus <command> [options]
+
+Options:
+  -V, --version                                            output the version number
+  -h, --help                                               display help for command
+
+Commands:
+  build [options] [siteDir]                                Build website.
+  swizzle [options] [themeName] [componentName] [siteDir]  Wraps or ejects the original theme files into website folder for customization.
+  deploy [options] [siteDir]                               Deploy website to GitHub pages.
+  start [options] [siteDir]                                Start the development server.
+  serve [options] [siteDir]                                Serve website locally.
+  clear [siteDir]                                          Remove build artifacts.
+  write-translations [options] [siteDir]                   Extract required translations of your site.
+  write-heading-ids [options] [siteDir] [files...]         Generate heading ids in Markdown content.
+  docs:version <version>                                   Tag a new docs version
+  gen-api-docs <id>                                        Generates API Docs mdx and sidebars.
+  clean-api-docs <id>                                      Clears the Generated API Docs mdx and sidebars.
+  docs:version:openapi <version>                           Tag a new docs version (openapi)
+```
+
+### Generating OpenAPI Docs
+
+To generate all OpenAPI docs, run the following command from the root directory of your project:
+
+```bash
+yarn docusaurus gen-api-docs all
+```
+
+> This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
+
+You may also generate OpenAPI docs for a single path or OAS by specifying the unique `id`:
+
+```bash
+yarn docusaurus gen-api-docs <id>
+```
+
+Example:
+
+```bash
+yarn docusaurus gen-api-docs burgers
+```
+
+> The example above will only generate API docs relative to `burgers`.
+
+### Cleaning API Docs
+
+To clean/remove all API Docs, run the following command from the root directory of your project:
+
+```bash
+yarn docusaurus clean-api-docs all
+```
+
+You may also remove a particular set of API docs by specifying the unique `id` of your desired spec instance.
+
+```bash
+yarn docusaurus clean-api-docs <id>
+```
+
+Example:
+
+```bash
+yarn docusaurus clean-api-docs burgers
+```
+
+> The example above will remove all API docs relative to `burgers`.
+
+## Support
+
+Please read [SUPPORT.md](SUPPORT.md) for details on how to get support for this project.

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/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/createFullWidthTable.d.ts

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

package/lib/markdown/createFullWidthTable.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.createFullWidthTable = void 0;
+const utils_1 = require("./utils");
+function createFullWidthTable({ children, style, ...rest }) {
+    return (0, utils_1.create)("table", {
+        style: { display: "table", width: "100%", ...style },
+        ...rest,
+        children,
+    });
+}
+exports.createFullWidthTable = createFullWidthTable;

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/createParamsTable.d.ts

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