docusaurus-plugin-openapi-docs 1.0.2 → 1.0.3

package/lib/types.d.ts

@@ -1,5 +1,5 @@
 import type Request from "@paloaltonetworks/postman-collection";
-import { InfoObject, OperationObject, SecuritySchemeObject } from "./openapi/types";
+import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
@@ -16,13 +16,15 @@ export interface APIOptions {
 export interface LoadedContent {
     loadedApi: ApiMetadata[];
 }
-export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
 export interface ApiMetadataBase {
     sidebar?: string;
     previous?: ApiNavLink;
     next?: ApiNavLink;
     id: string;
     unversionedId: string;
+    infoId?: string;
+    infoPath?: string;
     title: string;
     description: string;
     source: string;
@@ -52,6 +54,14 @@ export interface InfoPageMetadata extends ApiMetadataBase {
     type: "info";
     info: ApiInfo;
     markdown?: string;
+    securitySchemes?: {
+        [key: string]: SecuritySchemeObject;
+    };
+}
+export interface TagPageMetadata extends ApiMetadataBase {
+    type: "tag";
+    tag: TagObject;
+    markdown?: string;
 }
 export declare type ApiInfo = InfoObject;
 export interface ApiNavLink {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,20 +28,21 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.18",
-    "@docusaurus/types": "2.0.0-beta.18",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
     "@types/fs-extra": "^9.0.13",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
     "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",
+    "@docusaurus/mdx-loader": "2.0.0-beta.21",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
+    "@docusaurus/utils": "2.0.0-beta.21",
+    "@docusaurus/utils-validation": "2.0.0-beta.21",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
+    "@redocly/openapi-core": "^1.0.0-beta.100",
     "@types/js-yaml": "^4.0.5",
     "@types/mustache": "^4.1.2",
     "chalk": "^4.1.2",
@@ -52,6 +53,7 @@
     "json-schema-merge-allof": "^0.8.1",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
+    "swagger2openapi": "^7.0.8",
     "webpack": "^5.61.0"
   },
   "peerDependencies": {
@@ -60,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "526f2d10bc187bc7095ac70d5b1453b9b92c114f"
+  "gitHead": "618a438ec42148f525fb92cb11d291ce50d2ad06"
 }

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,11 +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, tags] = await processOpenapiFiles(openapiFiles);
+      const [loadedApi, tags] = await processOpenapiFiles(
+        openapiFiles,
+        sidebarOptions!
+      );
       if (!fs.existsSync(outputDir)) {
         try {
           fs.mkdirSync(outputDir, { recursive: true });
@@ -100,6 +109,9 @@ api: {{{json}}}
 {{#api.method}}
 sidebar_class_name: "{{{api.method}}} api-method"
 {{/api.method}}
+{{#infoPath}}
+info_path: {{{infoPath}}}
+{{/infoPath}}
 ---
 
 {{{markdown}}}
@@ -119,19 +131,45 @@ hide_title: true
 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`)) {
@@ -179,8 +217,31 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             }
           }
         }
+
+        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)
+              );
+            }
+          }
+        }
         return;
       });
+
       return;
     } catch (e) {
       console.error(chalk.red(`Loading of api failed for "${contentPath}"`));
@@ -191,7 +252,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
   async function cleanApiDocs(options: APIOptions) {
     const { outputDir } = options;
     const apiDir = path.join(siteDir, outputDir);
-    const apiMdxFiles = await Globby(["*.api.mdx", "*.info.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/index.ts

@@ -7,8 +7,13 @@
 
 import { escape } from "lodash";
 
-import { ContactObject, LicenseObject } from "../openapi/types";
-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";
@@ -50,13 +55,21 @@ export function createApiPageMD({
 
 export function createInfoPageMD({
   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)]);
+}

package/src/openapi/createExample.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import chalk from "chalk";
+
 import { SchemaObject } from "./types";
 
 interface OASTypeToTypeMap {
@@ -48,71 +50,78 @@ const primitives: Primitives = {
 };
 
 export const sampleFromSchema = (schema: SchemaObject = {}): any => {
-  let { type, example, allOf, properties, items } = schema;
+  try {
+    let { type, example, allOf, properties, items } = schema;
 
-  if (example !== undefined) {
-    return example;
-  }
+    if (example !== undefined) {
+      return example;
+    }
 
-  if (allOf) {
-    // TODO: We are just assuming it will always be an object for now
-    let obj: SchemaObject = {
-      type: "object",
-      properties: {},
-      required: [], // NOTE: We shouldn't need to worry about required
-    };
-    for (let item of allOf) {
-      if (item.properties) {
-        obj.properties = {
-          ...obj.properties,
-          ...item.properties,
-        };
+    if (allOf) {
+      // TODO: We are just assuming it will always be an object for now
+      let obj: SchemaObject = {
+        type: "object",
+        properties: {},
+        required: [], // NOTE: We shouldn't need to worry about required
+      };
+      for (let item of allOf) {
+        if (item.properties) {
+          obj.properties = {
+            ...obj.properties,
+            ...item.properties,
+          };
+        }
       }
+      return sampleFromSchema(obj);
     }
-    return sampleFromSchema(obj);
-  }
 
-  if (!type) {
-    if (properties) {
-      type = "object";
-    } else if (items) {
-      type = "array";
-    } else {
-      return;
+    if (!type) {
+      if (properties) {
+        type = "object";
+      } else if (items) {
+        type = "array";
+      } else {
+        return;
+      }
     }
-  }
 
-  if (type === "object") {
-    let obj: any = {};
-    for (let [name, prop] of Object.entries(properties ?? {})) {
-      if (prop.deprecated) {
-        continue;
+    if (type === "object") {
+      let obj: any = {};
+      for (let [name, prop] of Object.entries(properties ?? {})) {
+        if (prop.deprecated) {
+          continue;
+        }
+        obj[name] = sampleFromSchema(prop);
       }
-      obj[name] = sampleFromSchema(prop);
+      return obj;
     }
-    return obj;
-  }
 
-  if (type === "array") {
-    if (Array.isArray(items?.anyOf)) {
-      return items?.anyOf.map((item) => sampleFromSchema(item));
-    }
+    if (type === "array") {
+      if (Array.isArray(items?.anyOf)) {
+        return items?.anyOf.map((item) => sampleFromSchema(item));
+      }
 
-    if (Array.isArray(items?.oneOf)) {
-      return items?.oneOf.map((item) => sampleFromSchema(item));
-    }
+      if (Array.isArray(items?.oneOf)) {
+        return items?.oneOf.map((item) => sampleFromSchema(item));
+      }
 
-    return [sampleFromSchema(items)];
-  }
+      return [sampleFromSchema(items)];
+    }
 
-  if (schema.enum) {
-    if (schema.default) {
-      return schema.default;
+    if (schema.enum) {
+      if (schema.default) {
+        return schema.default;
+      }
+      return normalizeArray(schema.enum)[0];
     }
-    return normalizeArray(schema.enum)[0];
-  }
 
-  return primitive(schema);
+    return primitive(schema);
+  } catch (err) {
+    console.error(
+      chalk.yellow("WARNING: failed to create example from schema object:", err)
+    );
+    return;
+  }
 };
 
 function primitive(schema: SchemaObject = {}) {

package/src/openapi/openapi.test.ts

@@ -26,12 +26,6 @@ describe("openapi", () => {
       const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
       expect(yaml).toBeTruthy();
       expect(yaml?.sourceDirName).toBe(".");
-      const froyo = results.find((x) => x.source.endsWith("froyo.yaml"));
-      expect(froyo).toBeTruthy();
-      expect(froyo?.sourceDirName).toBe("yogurtstore");
-      const nested = results.find((x) => x.source.endsWith("nested.yaml"));
-      expect(nested).toBeTruthy();
-      expect(nested?.sourceDirName).toBe("yogurtstore/nested");
     });
   });
 });