docusaurus-plugin-openapi-docs 1.0.0

package/lib/sidebars/index.js

@@ -0,0 +1,89 @@
+"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 clsx_1 = __importDefault(require("clsx"));
+const uniq_1 = __importDefault(require("lodash/uniq"));
+function isApiItem(item) {
+    return item.type === "api";
+}
+function groupByTags(items, sidebarOptions, options) {
+    // TODO: Figure out how to handle these
+    // const intros = items.filter(isInfoItem).map((item) => {
+    //   return {
+    //     type: "link" as const,
+    //     label: item.title,
+    //     href: item.permalink,
+    //     docId: item.id,
+    //   };
+    // });
+    const { outputDir } = options;
+    const { sidebarCollapsed, sidebarCollapsible, customProps } = sidebarOptions;
+    const apiItems = items.filter(isApiItem);
+    // TODO: make sure we only take the first tag
+    const tags = (0, uniq_1.default)(apiItems
+        .flatMap((item) => item.api.tags)
+        .filter((item) => !!item));
+    // TODO: optimize this or make it a function
+    const basePath = outputDir
+        .slice(outputDir.indexOf("/", 1))
+        .replace(/^\/+/g, "");
+    function createDocItem(item) {
+        var _a, _b;
+        const sidebar_label = item.frontMatter.sidebar_label;
+        const title = item.title;
+        const id = item.id;
+        return {
+            type: "doc",
+            id: `${basePath}/${item.id}`,
+            label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
+            customProps: customProps,
+            className: (0, clsx_1.default)({
+                "menu__list-item--deprecated": item.api.deprecated,
+                "api-method": !!item.api.method,
+            }, item.api.method),
+        };
+    }
+    const tagged = tags
+        .map((tag) => {
+        return {
+            type: "category",
+            label: tag,
+            collapsible: sidebarCollapsible,
+            collapsed: sidebarCollapsed,
+            items: apiItems
+                .filter((item) => { var _a; return !!((_a = item.api.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); })
+                .map(createDocItem),
+        };
+    })
+        .filter((item) => item.items.length > 0); // Filter out any categories with no items.
+    // const untagged = [
+    //   // TODO: determine if needed and how
+    //   {
+    //     type: "category" as const,
+    //     label: "UNTAGGED",
+    //     // collapsible: options.sidebarCollapsible, TODO: add option
+    //     // collapsed: options.sidebarCollapsed, TODO: add option
+    //     items: apiItems
+    //       //@ts-ignore
+    //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+    //       .map(createDocItem),
+    //   },
+    // ];
+    return [...tagged];
+}
+function generateSidebarSlice(sidebarOptions, options, api) {
+    let sidebarSlice = [];
+    if (sidebarOptions.groupPathsBy === "tags") {
+        sidebarSlice = groupByTags(api, sidebarOptions, options);
+    }
+    return sidebarSlice;
+}
+exports.default = generateSidebarSlice;

package/lib/types.d.ts

@@ -0,0 +1,68 @@
+import type { Request } from "@paloaltonetworks/postman-collection";
+import { InfoObject, OperationObject, SecuritySchemeObject } from "./openapi/types";
+export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
+export interface PluginOptions {
+    id?: string;
+    config: {
+        [key: string]: APIOptions;
+    };
+}
+export interface APIOptions {
+    specPath: string;
+    outputDir: string;
+    template?: string;
+    sidebarOptions?: SidebarOptions;
+}
+export interface LoadedContent {
+    loadedApi: ApiMetadata[];
+}
+export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export interface ApiMetadataBase {
+    sidebar?: string;
+    previous?: ApiNavLink;
+    next?: ApiNavLink;
+    id: string;
+    unversionedId: string;
+    title: string;
+    description: string;
+    source: string;
+    sourceDirName: string;
+    slug: string;
+    permalink: string;
+    sidebarPosition?: number;
+    frontMatter: Record<string, unknown>;
+}
+export interface ApiPageMetadata extends ApiMetadataBase {
+    json?: string;
+    type: "api";
+    api: ApiItem;
+    markdown?: string;
+}
+export interface ApiItem extends OperationObject {
+    method: string;
+    path: string;
+    jsonRequestBodyExample: string;
+    securitySchemes?: {
+        [key: string]: SecuritySchemeObject;
+    };
+    postman?: Request;
+    info: InfoObject;
+}
+export interface InfoPageMetadata extends ApiMetadataBase {
+    type: "info";
+    info: ApiInfo;
+    markdown?: string;
+}
+export declare type ApiInfo = InfoObject;
+export interface ApiNavLink {
+    title: string;
+    permalink: string;
+}
+export interface SidebarOptions {
+    groupPathsBy?: string;
+    customProps?: {
+        [key: string]: unknown;
+    };
+    sidebarCollapsible?: boolean;
+    sidebarCollapsed?: boolean;
+}

package/lib/types.js

@@ -0,0 +1,8 @@
+"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 });

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "docusaurus-plugin-openapi-docs",
+  "description": "OpenAPI plugin for Docusaurus.",
+  "version": "1.0.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi.git",
+    "directory": "packages/docusaurus-plugin-openapi-docs"
+  },
+  "bugs": {
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi/issues"
+  },
+  "main": "lib/index.js",
+  "types": "src/plugin-openapi.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^2.0.0-beta.18",
+    "@docusaurus/types": "^2.0.0-beta.18",
+    "@types/fs-extra": "^9.0.13",
+    "@types/json-schema": "^7.0.9",
+    "@types/lodash": "^4.14.176",
+    "@types/postman-collection": "^3.5.7",
+    "utility-types": "^3.10.0"
+  },
+  "dependencies": {
+    "@docusaurus/mdx-loader": "^2.0.0-beta.18",
+    "@docusaurus/plugin-content-docs": "^2.0.0-beta.18",
+    "@docusaurus/utils": "^2.0.0-beta.18",
+    "@docusaurus/utils-validation": "^2.0.0-beta.18",
+    "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
+    "@paloaltonetworks/postman-collection": "^4.1.0",
+    "@types/js-yaml": "^4.0.5",
+    "@types/mustache": "^4.1.2",
+    "chalk": "^4.1.2",
+    "clsx": "^1.1.1",
+    "fs-extra": "^9.0.1",
+    "js-yaml": "^4.1.0",
+    "json-refs": "^3.0.15",
+    "json-schema-merge-allof": "^0.8.1",
+    "lodash": "^4.17.20",
+    "mustache": "^4.2.0",
+    "webpack": "^5.61.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "gitHead": "8905a438e86fc0a5cb9f033fb1b29630ff059af8"
+}

package/src/index.ts

@@ -0,0 +1,244 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import fs from "fs";
+import path from "path";
+
+import type { LoadContext, Plugin } from "@docusaurus/types";
+import { Globby } from "@docusaurus/utils";
+import chalk from "chalk";
+import { render } from "mustache";
+
+import { createApiPageMD, createInfoPageMD } from "./markdown";
+import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
+import generateSidebarSlice from "./sidebars";
+import type { PluginOptions, LoadedContent, APIOptions } from "./types";
+
+export default function pluginOpenAPI(
+  context: LoadContext,
+  options: PluginOptions
+): Plugin<LoadedContent> {
+  let { config } = options;
+  let { siteDir } = context;
+
+  async function generateApiDocs(options: APIOptions) {
+    let { specPath, outputDir, template, sidebarOptions } = options;
+
+    const contentPath = path.resolve(siteDir, specPath);
+
+    try {
+      const openapiFiles = await readOpenapiFiles(contentPath, {});
+      const loadedApi = await processOpenapiFiles(openapiFiles);
+
+      if (!fs.existsSync(outputDir)) {
+        try {
+          fs.mkdirSync(outputDir, { recursive: true });
+          console.log(chalk.green(`Successfully created "${outputDir}"`));
+        } catch (err) {
+          console.error(
+            chalk.red(`Failed to create "${outputDir}"`),
+            chalk.yellow(err)
+          );
+        }
+      }
+
+      // TODO: figure out better way to set default
+      if (Object.keys(sidebarOptions ?? {}).length > 0) {
+        const sidebarSlice = generateSidebarSlice(
+          sidebarOptions!, // TODO: find a better way to handle null
+          options,
+          loadedApi
+        );
+
+        const sidebarSliceTemplate = template
+          ? fs.readFileSync(template).toString()
+          : `module.exports = {{{slice}}};`;
+
+        const view = render(sidebarSliceTemplate, {
+          slice: JSON.stringify(sidebarSlice),
+        });
+
+        if (!fs.existsSync(`${outputDir}/sidebar.js`)) {
+          try {
+            fs.writeFileSync(`${outputDir}/sidebar.js`, view, "utf8");
+            console.log(
+              chalk.green(`Successfully created "${outputDir}/sidebar.js"`)
+            );
+          } catch (err) {
+            console.error(
+              chalk.red(`Failed to write "${outputDir}/sidebar.js"`),
+              chalk.yellow(err)
+            );
+          }
+        }
+      }
+
+      const mdTemplate = template
+        ? fs.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" ? createApiPageMD(item) : createInfoPageMD(item);
+        item.markdown = markdown;
+        if (item.type === "api") {
+          item.json = JSON.stringify(item.api);
+        }
+        const view = render(mdTemplate, item);
+
+        if (item.type === "api") {
+          if (!fs.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
+            try {
+              fs.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
+              console.log(
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.api.mdx"`
+                )
+              );
+            } catch (err) {
+              console.error(
+                chalk.red(`Failed to write "${outputDir}/${item.id}.api.mdx"`),
+                chalk.yellow(err)
+              );
+            }
+          }
+        }
+
+        // TODO: determine if we actually want/need this
+        if (item.type === "info") {
+          if (!fs.existsSync(`${outputDir}/index.api.mdx`)) {
+            try {
+              fs.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
+              console.log(
+                chalk.green(`Successfully created "${outputDir}/index.api.mdx"`)
+              );
+            } catch (err) {
+              console.error(
+                chalk.red(`Failed to write "${outputDir}/index.api.mdx"`),
+                chalk.yellow(err)
+              );
+            }
+          }
+        }
+        return;
+      });
+      return;
+    } catch (e) {
+      console.error(chalk.red(`Loading of api failed for "${contentPath}"`));
+      throw e;
+    }
+  }
+
+  async function cleanApiDocs(options: APIOptions) {
+    const { outputDir } = options;
+    const apiDir = path.join(siteDir, outputDir);
+    const apiMdxFiles = await Globby(["*.api.mdx"], {
+      cwd: path.resolve(apiDir),
+    });
+    const sidebarFile = await Globby(["sidebar.js"], {
+      cwd: path.resolve(apiDir),
+    });
+    apiMdxFiles.map((mdx) =>
+      fs.unlink(`${apiDir}/${mdx}`, (err) => {
+        if (err) {
+          console.error(
+            chalk.red(`Cleanup failed for "${apiDir}/${mdx}"`),
+            chalk.yellow(err)
+          );
+        } else {
+          console.log(chalk.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
+        }
+      })
+    );
+
+    sidebarFile.map((sidebar) =>
+      fs.unlink(`${apiDir}/${sidebar}`, (err) => {
+        if (err) {
+          console.error(
+            chalk.red(`Cleanup failed for "${apiDir}/${sidebar}"`),
+            chalk.yellow(err)
+          );
+        } else {
+          console.log(
+            chalk.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`)
+          );
+        }
+      })
+    );
+  }
+
+  return {
+    name: `docusaurus-plugin-openapi`,
+
+    extendCli(cli): void {
+      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.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.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.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]);
+          }
+        });
+    },
+  };
+}

package/src/markdown/createDeprecationNotice.ts

@@ -0,0 +1,30 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { guard, Props, render } from "./utils";
+
+function createAdmonition({ children }: Props) {
+  return `:::caution deprecated\n\n${render(children)}\n\n:::`;
+}
+
+interface DeprecationNoticeProps {
+  deprecated?: boolean;
+  description?: string;
+}
+
+export function createDeprecationNotice({
+  deprecated,
+  description,
+}: DeprecationNoticeProps) {
+  return guard(deprecated, () =>
+    createAdmonition({
+      children:
+        description ??
+        "This endpoint has been deprecated and may be removed in future versions of the API.",
+    })
+  );
+}

package/src/markdown/createDescription.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+export function createDescription(description: string | undefined) {
+  if (!description) {
+    return "";
+  }
+  return `\n\n${description}\n\n`;
+}

package/src/markdown/createDetails.ts

@@ -0,0 +1,16 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { create, Props } from "./utils";
+
+export function createDetails({ children, style, ...rest }: Props) {
+  return create("details", {
+    style: { ...style },
+    ...rest,
+    children,
+  });
+}

package/src/markdown/createDetailsSummary.ts

@@ -0,0 +1,16 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { create, Props } from "./utils";
+
+export function createDetailsSummary({ children, style, ...rest }: Props) {
+  return create("summary", {
+    style: { ...style },
+    ...rest,
+    children,
+  });
+}

package/src/markdown/createFullWidthTable.ts

@@ -0,0 +1,16 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { create, Props } from "./utils";
+
+export function createFullWidthTable({ children, style, ...rest }: Props) {
+  return create("table", {
+    style: { display: "table", width: "100%", ...style },
+    ...rest,
+    children,
+  });
+}

package/src/markdown/createParamsDetails.ts

@@ -0,0 +1,53 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { ApiItem } from "../types";
+import { createDetails } from "./createDetails";
+import { createDetailsSummary } from "./createDetailsSummary";
+import { create } from "./utils";
+
+interface Props {
+  parameters: ApiItem["parameters"];
+  type: "path" | "query" | "header" | "cookie";
+}
+
+export function createParamsDetails({ parameters, type }: Props) {
+  if (parameters === undefined) {
+    return undefined;
+  }
+  const params = parameters.filter((param) => param?.in === type);
+  if (params.length === 0) {
+    return undefined;
+  }
+
+  return createDetails({
+    style: { marginBottom: "1rem" },
+    children: [
+      createDetailsSummary({
+        children: [
+          create("strong", {
+            children: `${
+              type.charAt(0).toUpperCase() + type.slice(1)
+            } Parameters`,
+          }),
+        ],
+      }),
+      create("div", {
+        children: [
+          create("ul", {
+            children: params.map((param) =>
+              create("ParamsItem", {
+                className: "paramsItem",
+                param: param,
+              })
+            ),
+          }),
+        ],
+      }),
+    ],
+  });
+}