docusaurus-plugin-openapi-docs 1.0.0 → 1.0.3

package/src/index.ts

@@ -13,11 +13,15 @@ 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 generateSidebarSlice from "./sidebars";
 import type { PluginOptions, LoadedContent, APIOptions } from "./types";
 
+export function isURL(str: string): boolean {
+  return /^(https?:)\/\//m.test(str);
+}
+
 export default function pluginOpenAPI(
   context: LoadContext,
   options: PluginOptions
@@ -28,12 +32,16 @@ export default function pluginOpenAPI(
   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 });
@@ -51,7 +59,8 @@ export default function pluginOpenAPI(
         const sidebarSlice = generateSidebarSlice(
           sidebarOptions!, // TODO: find a better way to handle null
           options,
-          loadedApi
+          loadedApi,
+          tags
         );
 
         const sidebarSliceTemplate = template
@@ -81,7 +90,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 +109,67 @@ 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);
+          if (item.infoId) item.infoPath = `${outputDir}/${item.infoId}`;
         }
+
         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 +191,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 {
-              fs.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
+              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}/index.api.mdx"`)
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.info.mdx"`
+                )
               );
             } catch (err) {
               console.error(
-                chalk.red(`Failed to write "${outputDir}/index.api.mdx"`),
+                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}/${item.id}.tag.mdx`,
+                tagUtils,
+                "utf8"
+              );
+              console.log(
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.tag.mdx"`
+                )
+              );
+            } catch (err) {
+              console.error(
+                chalk.red(`Failed to write "${outputDir}/${item.id}.tag.mdx"`),
                 chalk.yellow(err)
               );
             }
@@ -145,6 +241,7 @@ sidebar_class_name: "{{{api.method}}} api-method"
         }
         return;
       });
+
       return;
     } catch (e) {
       console.error(chalk.red(`Loading of api failed for "${contentPath}"`));
@@ -155,7 +252,7 @@ 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),
     });
     const sidebarFile = await Globby(["sidebar.js"], {

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}`,
+            }),
+          ],
+        })
+      ),
+    ],
+  });
+}

package/src/markdown/createLicense.ts

@@ -0,0 +1,34 @@
+/* ============================================================================
+ * 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 { LicenseObject } from "../openapi/types";
+import { create, guard } from "./utils";
+
+export function createLicense(license: LicenseObject) {
+  if (!license || !Object.keys(license).length) return "";
+  const { name, url } = license;
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "License",
+      }),
+      guard(url, () =>
+        create("a", {
+          href: url,
+          children: name ?? url,
+        })
+      ),
+    ],
+  });
+}

package/src/markdown/createSchemaDetails.ts

@@ -242,7 +242,12 @@ interface Props {
 }
 
 export function createSchemaDetails({ title, body, ...rest }: Props) {
-  if (body === undefined || body.content === undefined) {
+  if (
+    body === undefined ||
+    body.content === undefined ||
+    Object.keys(body).length === 0 ||
+    Object.keys(body.content).length === 0
+  ) {
     return undefined;
   }
 
@@ -250,7 +255,6 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
   // NOTE: We just pick a random content-type.
   // How common is it to have multiple?
   const randomFirstKey = Object.keys(body.content)[0];
-
   const firstBody = body.content[randomFirstKey].schema;
 
   if (firstBody === undefined) {

package/src/markdown/createStatusCodes.ts

@@ -26,7 +26,7 @@ export function createStatusCodes({ responses }: Props) {
 
   return create("div", {
     children: [
-      create("Tabs", {
+      create("ApiTabs", {
         children: codes.map((code) => {
           return create("TabItem", {
             label: code,

package/src/markdown/createTermsOfService.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 { create } from "./utils";
+
+export function createTermsOfService(termsOfService: string | undefined) {
+  if (!termsOfService) return "";
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "Terms of Service",
+      }),
+      create("a", {
+        href: `${termsOfService}`,
+        children: termsOfService,
+      }),
+    ],
+  });
+}

package/src/markdown/index.ts

@@ -7,12 +7,21 @@
 
 import { escape } from "lodash";
 
-import { ApiPageMetadata, InfoPageMetadata } from "../types";
+import {
+  ContactObject,
+  LicenseObject,
+  SecuritySchemeObject,
+} from "../openapi/types";
+import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
+import { createAuthentication } from "./createAuthentication";
+import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
+import { createLicense } from "./createLicense";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
+import { createTermsOfService } from "./createTermsOfService";
 import { createVersionBadge } from "./createVersionBadge";
 import { render } from "./utils";
 
@@ -30,7 +39,7 @@ export function createApiPageMD({
   return render([
     `import ParamsItem from "@theme/ParamsItem";\n`,
     `import SchemaItem from "@theme/SchemaItem"\n`,
-    `import Tabs from "@theme/Tabs";\n`,
+    `import ApiTabs from "@theme/ApiTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
@@ -45,11 +54,22 @@ export function createApiPageMD({
 }
 
 export function createInfoPageMD({
-  info: { title, version, description },
+  info: { title, version, description, contact, license, termsOfService },
+  securitySchemes,
 }: InfoPageMetadata) {
   return render([
+    `import Tabs from "@theme/Tabs";\n`,
+    `import TabItem from "@theme/TabItem";\n`,
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
     createDescription(description),
+    createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
+    createContactInfo(contact as ContactObject),
+    createTermsOfService(termsOfService),
+    createLicense(license as LicenseObject),
   ]);
 }
+
+export function createTagPageMD({ tag: { description } }: TagPageMetadata) {
+  return render([createDescription(description)]);
+}