docusaurus-plugin-openapi-docs 1.0.1 → 1.0.4

package/src/index.ts

@@ -13,27 +13,79 @@ import { Globby } from "@docusaurus/utils";
 import chalk from "chalk";
 import { render } from "mustache";
 
-import { createApiPageMD, createInfoPageMD } from "./markdown";
+import { createApiPageMD, createInfoPageMD, createTagPageMD } from "./markdown";
 import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
+import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
 import type { PluginOptions, LoadedContent, APIOptions } from "./types";
 
-export default function pluginOpenAPI(
+export function isURL(str: string): boolean {
+  return /^(https?:)\/\//m.test(str);
+}
+
+export function getDocsData(
+  dataArray: any[],
+  filter: string
+): Object | undefined {
+  // eslint-disable-next-line array-callback-return
+  const filteredData = dataArray.filter((data) => {
+    if (data[0] === filter) {
+      return data[1];
+    }
+
+    // Search plugin-content-docs instances
+    if (data[0] === "@docusaurus/plugin-content-docs") {
+      const pluginId = data[1].id ? data[1].id : "default";
+      if (pluginId === filter) {
+        return data[1];
+      }
+    }
+  })[0];
+  if (filteredData) {
+    // Search presets, e.g. "classic"
+    if (filteredData[0] === filter) {
+      return filteredData[1].docs;
+    }
+
+    // Search plugin-content-docs instances
+    if (filteredData[0] === "@docusaurus/plugin-content-docs") {
+      const pluginId = filteredData[1].id ? filteredData[1].id : "default";
+      if (pluginId === filter) {
+        return filteredData[1];
+      }
+    }
+  }
+  return;
+}
+
+export default function pluginOpenAPIDocs(
   context: LoadContext,
   options: PluginOptions
 ): Plugin<LoadedContent> {
-  let { config } = options;
-  let { siteDir } = context;
+  const { config, docPluginId } = options;
+  const { siteDir, siteConfig } = context;
+
+  // Get routeBasePath and path from plugin-content-docs or preset
+  const presets: any = siteConfig.presets;
+  const plugins: any = siteConfig.plugins;
+  const presetsPlugins = presets.concat(plugins);
+  const docData: any = getDocsData(presetsPlugins, docPluginId);
+  const docRouteBasePath = docData ? docData.routeBasePath : undefined;
+  const docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
 
   async function generateApiDocs(options: APIOptions) {
     let { specPath, outputDir, template, sidebarOptions } = options;
 
-    const contentPath = path.resolve(siteDir, specPath);
+    const contentPath = isURL(specPath)
+      ? specPath
+      : path.resolve(siteDir, specPath);
 
     try {
       const openapiFiles = await readOpenapiFiles(contentPath, {});
-      const loadedApi = await processOpenapiFiles(openapiFiles);
-
+      const [loadedApi, tags] = await processOpenapiFiles(
+        openapiFiles,
+        sidebarOptions!
+      );
       if (!fs.existsSync(outputDir)) {
         try {
           fs.mkdirSync(outputDir, { recursive: true });
@@ -49,9 +101,11 @@ export default function pluginOpenAPI(
       // 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
+          sidebarOptions!,
           options,
-          loadedApi
+          loadedApi,
+          tags,
+          docPath
         );
 
         const sidebarSliceTemplate = template
@@ -81,7 +135,12 @@ export default function pluginOpenAPI(
         ? fs.readFileSync(template).toString()
         : `---
 id: {{{id}}}
+{{^api}}
+sidebar_label: Introduction
+{{/api}}
+{{#api}}
 sidebar_label: {{{title}}}
+{{/api}}
 {{^api}}
 sidebar_position: 0
 {{/api}}
@@ -95,19 +154,73 @@ api: {{{json}}}
 {{#api.method}}
 sidebar_class_name: "{{{api.method}}} api-method"
 {{/api.method}}
+{{#infoPath}}
+info_path: {{{infoPath}}}
+{{/infoPath}}
+---
+
+{{{markdown}}}
+      `;
+
+      const infoMdTemplate = template
+        ? fs.readFileSync(template).toString()
+        : `---
+id: {{{id}}}
+sidebar_label: {{{title}}}
+hide_title: true
+---
+
+{{{markdown}}}
+
+\`\`\`mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+\`\`\`
+      `;
+
+      const tagMdTemplate = template
+        ? fs.readFileSync(template).toString()
+        : `---
+id: {{{id}}}
+title: {{{description}}}
+description: {{{description}}}
 ---
 
 {{{markdown}}}
+
+\`\`\`mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+\`\`\`
       `;
 
       loadedApi.map(async (item) => {
         const markdown =
-          item.type === "api" ? createApiPageMD(item) : createInfoPageMD(item);
+          item.type === "api"
+            ? createApiPageMD(item)
+            : item.type === "info"
+            ? createInfoPageMD(item)
+            : createTagPageMD(item);
         item.markdown = markdown;
         if (item.type === "api") {
           item.json = JSON.stringify(item.api);
+          let infoBasePath = `${outputDir}/${item.infoId}`;
+          if (docRouteBasePath) {
+            infoBasePath = `${docRouteBasePath}/${outputDir
+              .split(docPath!)[1]
+              .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+          }
+          if (item.infoId) item.infoPath = infoBasePath;
         }
+
         const view = render(mdTemplate, item);
+        const utils = render(infoMdTemplate, item);
+        // eslint-disable-next-line testing-library/render-result-naming-convention
+        const tagUtils = render(tagMdTemplate, item);
 
         if (item.type === "api") {
           if (!fs.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
@@ -129,15 +242,49 @@ sidebar_class_name: "{{{api.method}}} api-method"
 
         // TODO: determine if we actually want/need this
         if (item.type === "info") {
-          if (!fs.existsSync(`${outputDir}/index.api.mdx`)) {
+          if (!fs.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
+            try {
+              sidebarOptions?.categoryLinkSource === "info" // Only use utils template if set to "info"
+                ? fs.writeFileSync(
+                    `${outputDir}/${item.id}.info.mdx`,
+                    utils,
+                    "utf8"
+                  )
+                : fs.writeFileSync(
+                    `${outputDir}/${item.id}.info.mdx`,
+                    view,
+                    "utf8"
+                  );
+              console.log(
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.info.mdx"`
+                )
+              );
+            } catch (err) {
+              console.error(
+                chalk.red(`Failed to write "${outputDir}/${item.id}.info.mdx"`),
+                chalk.yellow(err)
+              );
+            }
+          }
+        }
+
+        if (item.type === "tag") {
+          if (!fs.existsSync(`${outputDir}/${item.id}.tag.mdx`)) {
             try {
-              fs.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
+              fs.writeFileSync(
+                `${outputDir}/${item.id}.tag.mdx`,
+                tagUtils,
+                "utf8"
+              );
               console.log(
-                chalk.green(`Successfully created "${outputDir}/index.api.mdx"`)
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.tag.mdx"`
+                )
               );
             } catch (err) {
               console.error(
-                chalk.red(`Failed to write "${outputDir}/index.api.mdx"`),
+                chalk.red(`Failed to write "${outputDir}/${item.id}.tag.mdx"`),
                 chalk.yellow(err)
               );
             }
@@ -145,6 +292,7 @@ sidebar_class_name: "{{{api.method}}} api-method"
         }
         return;
       });
+
       return;
     } catch (e) {
       console.error(chalk.red(`Loading of api failed for "${contentPath}"`));
@@ -155,11 +303,13 @@ sidebar_class_name: "{{{api.method}}} api-method"
   async function cleanApiDocs(options: APIOptions) {
     const { outputDir } = options;
     const apiDir = path.join(siteDir, outputDir);
-    const apiMdxFiles = await Globby(["*.api.mdx"], {
+    const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
       cwd: path.resolve(apiDir),
+      deep: 1,
     });
     const sidebarFile = await Globby(["sidebar.js"], {
       cwd: path.resolve(apiDir),
+      deep: 1,
     });
     apiMdxFiles.map((mdx) =>
       fs.unlink(`${apiDir}/${mdx}`, (err) => {
@@ -190,21 +340,66 @@ sidebar_class_name: "{{{api.method}}} api-method"
     );
   }
 
+  async function generateVersions(versions: object, outputDir: string) {
+    let versionsArray = [] as object[];
+    for (const [version, metadata] of Object.entries(versions)) {
+      versionsArray.push({
+        version: version,
+        label: metadata.label,
+        baseUrl: metadata.baseUrl,
+      });
+    }
+
+    const versionsJson = JSON.stringify(versionsArray, null, 2);
+    try {
+      fs.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+      console.log(
+        chalk.green(`Successfully created "${outputDir}/versions.json"`)
+      );
+    } catch (err) {
+      console.error(
+        chalk.red(`Failed to write "${outputDir}/versions.json"`),
+        chalk.yellow(err)
+      );
+    }
+  }
+
+  async function cleanVersions(outputDir: string) {
+    if (fs.existsSync(`${outputDir}/versions.json`)) {
+      fs.unlink(`${outputDir}/versions.json`, (err) => {
+        if (err) {
+          console.error(
+            chalk.red(`Cleanup failed for "${outputDir}/versions.json"`),
+            chalk.yellow(err)
+          );
+        } else {
+          console.log(
+            chalk.green(`Cleanup succeeded for "${outputDir}/versions.json"`)
+          );
+        }
+      });
+    }
+  }
+
   return {
-    name: `docusaurus-plugin-openapi`,
+    name: `docusaurus-plugin-openapi-docs`,
 
     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>"
+        .description(
+          `Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`
         )
+        .usage("<id>")
         .arguments("<id>")
         .action(async (id) => {
           if (id === "all") {
             if (config[id]) {
-              console.error(chalk.red("Can't use id 'all' for API Doc."));
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs configuration key."
+                )
+              );
             } else {
               Object.keys(config).forEach(async function (key) {
                 await generateApiDocs(config[key]);
@@ -212,24 +407,91 @@ sidebar_class_name: "{{{api.method}}} api-method"
             }
           } else if (!config[id]) {
             console.error(
-              chalk.red(`ID ${id} does not exist in openapi-plugin config`)
+              chalk.red(`ID '${id}' does not exist in OpenAPI docs config.`)
             );
           } else {
             await generateApiDocs(config[id]);
           }
         });
 
+      cli
+        .command(`gen-api-docs:version`)
+        .description(
+          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`
+        )
+        .usage("<id:version>")
+        .arguments("<id:version>")
+        .action(async (id) => {
+          const [parentId, versionId] = id.split(":");
+          const parentConfig = Object.assign({}, config[parentId]);
+
+          const version = parentConfig.version as string;
+          const label = parentConfig.label as string;
+          const baseUrl = parentConfig.baseUrl as string;
+
+          let parentVersion = {} as any;
+          parentVersion[version] = { label: label, baseUrl: baseUrl };
+
+          const { versions } = config[parentId] as any;
+          const mergedVersions = Object.assign(parentVersion, versions);
+
+          // Prepare for merge
+          delete parentConfig.versions;
+          delete parentConfig.version;
+          delete parentConfig.label;
+          delete parentConfig.baseUrl;
+
+          // TODO: handle when no versions are defined by version command is passed
+          if (versionId === "all") {
+            if (versions[id]) {
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs versions configuration key."
+                )
+              );
+            } else {
+              await generateVersions(mergedVersions, parentConfig.outputDir);
+              Object.keys(versions).forEach(async (key) => {
+                const versionConfig = versions[key];
+                const mergedConfig = {
+                  ...parentConfig,
+                  ...versionConfig,
+                };
+                await generateApiDocs(mergedConfig);
+              });
+            }
+          } else if (!versions[versionId]) {
+            console.error(
+              chalk.red(
+                `Version ID '${versionId}' does not exist in OpenAPI docs versions config.`
+              )
+            );
+          } else {
+            const versionConfig = versions[versionId];
+            const mergedConfig = {
+              ...parentConfig,
+              ...versionConfig,
+            };
+            await generateVersions(mergedVersions, parentConfig.outputDir);
+            await generateApiDocs(mergedConfig);
+          }
+        });
+
       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>"
+        .description(
+          `Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`
         )
+        .usage("<id>")
         .arguments("<id>")
         .action(async (id) => {
           if (id === "all") {
             if (config[id]) {
-              console.error(chalk.red("Can't use id 'all' for API Doc."));
+              console.error(
+                chalk.red(
+                  "Can't use id 'all' for OpenAPI docs configuration key."
+                )
+              );
             } else {
               Object.keys(config).forEach(async function (key) {
                 await cleanApiDocs(config[key]);
@@ -239,6 +501,51 @@ sidebar_class_name: "{{{api.method}}} api-method"
             await cleanApiDocs(config[id]);
           }
         });
+
+      cli
+        .command(`clean-api-docs:version`)
+        .description(
+          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`
+        )
+        .usage("<id:version>")
+        .arguments("<id:version>")
+        .action(async (id) => {
+          const [parentId, versionId] = id.split(":");
+          const { versions } = config[parentId] as any;
+
+          const parentConfig = Object.assign({}, config[parentId]);
+          delete parentConfig.versions;
+
+          if (versionId === "all") {
+            if (versions[id]) {
+              chalk.red(
+                "Can't use id 'all' for OpenAPI docs versions configuration key."
+              );
+            } else {
+              await cleanVersions(parentConfig.outputDir);
+              Object.keys(versions).forEach(async (key) => {
+                const versionConfig = versions[key];
+                const mergedConfig = {
+                  ...parentConfig,
+                  ...versionConfig,
+                };
+                await cleanApiDocs(mergedConfig);
+              });
+            }
+          } else {
+            const versionConfig = versions[versionId];
+            const mergedConfig = {
+              ...parentConfig,
+              ...versionConfig,
+            };
+            await cleanApiDocs(mergedConfig);
+          }
+        });
     },
   };
 }
+
+pluginOpenAPIDocs.validateOptions = ({ options, validate }: any) => {
+  const validatedOptions = validate(OptionsSchema, options);
+  return validatedOptions;
+};

package/src/markdown/createAuthentication.ts

@@ -0,0 +1,160 @@
+/* ============================================================================
+ * 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 { OAuthFlowObject, SecuritySchemeObject } from "../openapi/types";
+import { createDescription } from "./createDescription";
+import { create, guard } from "./utils";
+
+export function createAuthentication(securitySchemes: SecuritySchemeObject) {
+  if (!securitySchemes || !Object.keys(securitySchemes).length) return "";
+
+  const createAuthenticationTable = (securityScheme: any) => {
+    const { bearerFormat, flows, name, scheme, type } = securityScheme;
+
+    const createSecuritySchemeTypeRow = () =>
+      create("tr", {
+        children: [
+          create("th", { children: "Security Scheme Type:" }),
+          create("td", { children: type }),
+        ],
+      });
+
+    const createOAuthFlowRows = () => {
+      const flowRows = Object.entries(flows).map(([flowType, flowObj]) => {
+        const { authorizationUrl, tokenUrl, refreshUrl, scopes } =
+          flowObj as OAuthFlowObject;
+
+        return create("tr", {
+          children: [
+            create("th", { children: `${flowType} OAuth Flow:` }),
+            create("td", {
+              children: [
+                guard(tokenUrl, () =>
+                  create("p", { children: `Token URL: ${tokenUrl}` })
+                ),
+                guard(authorizationUrl, () =>
+                  create("p", {
+                    children: `Authorization URL: ${authorizationUrl}`,
+                  })
+                ),
+                guard(refreshUrl, () =>
+                  create("p", { children: `Refresh URL: ${refreshUrl}` })
+                ),
+                create("span", { children: "Scopes:" }),
+                create("ul", {
+                  children: Object.entries(scopes).map(([scope, description]) =>
+                    create("li", { children: `${scope}: ${description}` })
+                  ),
+                }),
+              ],
+            }),
+          ],
+        });
+      });
+
+      return flowRows.join("");
+    };
+
+    switch (type) {
+      case "apiKey":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "Header parameter name:" }),
+                      create("td", { children: name }),
+                    ],
+                  }),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "http":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "HTTP Authorization Scheme:" }),
+                      create("td", { children: scheme }),
+                    ],
+                  }),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "Bearer format:" }),
+                      create("td", { children: bearerFormat }),
+                    ],
+                  }),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "oauth2":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  createOAuthFlowRows(),
+                ],
+              }),
+            }),
+          ],
+        });
+      default:
+        return "";
+    }
+  };
+
+  const formatTabLabel = (str: string) => {
+    const formattedLabel = str
+      .replace(/(_|-)/g, " ")
+      .trim()
+      .replace(/\w\S*/g, (str) => str.charAt(0).toUpperCase() + str.substr(1))
+      .replace(/([a-z])([A-Z])/g, "$1 $2")
+      .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+
+    const isOAuth = formattedLabel.toLowerCase().includes("oauth2");
+    const isApiKey = formattedLabel.toLowerCase().includes("api");
+
+    return isOAuth ? "OAuth 2.0" : isApiKey ? "API Key" : formattedLabel;
+  };
+
+  return create("div", {
+    children: [
+      create("h2", {
+        children: "Authentication",
+        id: "authentication",
+        style: { marginBottom: "1rem" },
+      }),
+      create("Tabs", {
+        children: Object.entries(securitySchemes).map(
+          ([schemeType, schemeObj]) =>
+            create("TabItem", {
+              label: formatTabLabel(schemeType),
+              value: `${schemeType}`,
+              children: [
+                createDescription(schemeObj.description),
+                createAuthenticationTable(schemeObj),
+              ],
+            })
+        ),
+      }),
+    ],
+    style: { marginBottom: "2rem" },
+  });
+}

package/src/markdown/createContactInfo.ts

@@ -0,0 +1,52 @@
+/* ============================================================================
+ * 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 { ContactObject } from "../openapi/types";
+import { create, guard } from "./utils";
+
+export function createContactInfo(contact: ContactObject) {
+  if (!contact || !Object.keys(contact).length) return "";
+  const { name, url, email } = contact;
+
+  return create("div", {
+    style: {
+      display: "flex",
+      flexDirection: "column",
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "Contact",
+      }),
+      create("span", {
+        children: [
+          guard(name, () => `${name}: `),
+          guard(email, () =>
+            create("a", {
+              href: `mailto:${email}`,
+              children: `${email}`,
+            })
+          ),
+        ],
+      }),
+      guard(url, () =>
+        create("span", {
+          children: [
+            "URL: ",
+            create("a", {
+              href: `${url}`,
+              children: `${url}`,
+            }),
+          ],
+        })
+      ),
+    ],
+  });
+}