docusaurus-plugin-openapi-docs 4.5.0 → 4.6.0

package/src/openapi/openapi.ts

@@ -43,9 +43,15 @@ function jsonToCollection(data: OpenApiObject): Promise<Collection> {
       { schemaFaker: false }
     );
     schemaPack.computedOptions.schemaFaker = false;
+
+    // Make sure the schema was properly validated or reject with error
+    if (!schemaPack.validationResult?.result) {
+      return reject(schemaPack.validationResult?.reason);
+    }
+
     schemaPack.convert((_err: any, conversionResult: any) => {
-      if (!conversionResult.result) {
-        return reject(conversionResult.reason);
+      if (_err || !conversionResult.result) {
+        return reject(_err || conversionResult.reason);
       }
       return resolve(new sdk.Collection(conversionResult.output[0].data));
     });
@@ -89,9 +95,13 @@ function createItems(
   let items: PartialPage<ApiMetadata>[] = [];
   const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
   const infoId = kebabCase(infoIdSpaces);
+  const schemasOnly = options?.schemasOnly === true;
 
-  if (openapiData.info.description || openapiData.info.title) {
-    // Only create an info page if we have a description.
+  // Only create an info page if we have a description/title AND showInfoPage is not false
+  if (
+    (openapiData.info.description || openapiData.info.title) &&
+    options?.showInfoPage !== false
+  ) {
     const infoDescription = openapiData.info?.description;
     let splitDescription: any;
     if (infoDescription) {
@@ -250,6 +260,9 @@ function createItems(
           ...(options?.showExtensions && {
             show_extensions: options.showExtensions,
           }),
+          ...(options?.maskCredentials === false && {
+            mask_credentials_disabled: true,
+          }),
         },
         api: {
           ...defaults,
@@ -274,11 +287,19 @@ function createItems(
   for (let [path, pathObject] of Object.entries(
     openapiData["x-webhooks"] ?? openapiData["webhooks"] ?? {}
   )) {
+    const eventName = path;
     path = "webhook";
     const { $ref, description, parameters, servers, summary, ...rest } =
       pathObject;
     for (let [method, operationObject] of Object.entries({ ...rest })) {
       method = "event";
+      if (
+        operationObject.summary === undefined &&
+        operationObject.operationId === undefined
+      ) {
+        operationObject.summary = eventName;
+      }
+
       const title =
         operationObject.summary ??
         operationObject.operationId ??
@@ -290,7 +311,7 @@ function createItems(
 
       const baseId = operationObject.operationId
         ? kebabCase(operationObject.operationId)
-        : kebabCase(operationObject.summary);
+        : kebabCase(operationObject.summary ?? eventName);
 
       const extensions = [];
       const commonExtensions = ["x-codeSamples"];
@@ -395,6 +416,9 @@ function createItems(
           ...(options?.showExtensions && {
             show_extensions: options.showExtensions,
           }),
+          ...(options?.maskCredentials === false && {
+            mask_credentials_disabled: true,
+          }),
         },
         api: {
           ...defaults,
@@ -414,6 +438,7 @@ function createItems(
   }
 
   if (
+    schemasOnly ||
     options?.showSchemas === true ||
     Object.entries(openapiData?.components?.schemas ?? {})
       .flatMap(([_, s]) => s["x-tags"])
@@ -423,7 +448,11 @@ function createItems(
     for (let [schema, schemaObject] of Object.entries(
       openapiData?.components?.schemas ?? {}
     )) {
-      if (options?.showSchemas === true || schemaObject["x-tags"]) {
+      if (
+        schemasOnly ||
+        options?.showSchemas === true ||
+        schemaObject["x-tags"]
+      ) {
         const baseIdSpaces =
           schemaObject?.title?.replace(" ", "-").toLowerCase() ?? "";
         const baseId = kebabCase(baseIdSpaces);

package/src/openapi/webhooks.test.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 path from "path";
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { posixPath } from "@docusaurus/utils";
+
+import { readOpenapiFiles, processOpenapiFiles } from ".";
+
+describe("webhooks", () => {
+  it("uses event name when summary and operationId are missing", async () => {
+    const files = await readOpenapiFiles(
+      posixPath(path.join(__dirname, "__fixtures__/webhook/openapi.yaml"))
+    );
+
+    const [items] = await processOpenapiFiles(
+      files,
+      { specPath: "", outputDir: "" } as any,
+      {}
+    );
+
+    const webhookItem = items.find((item) => item.type === "api");
+    expect(webhookItem?.id).toBe("order-created");
+  });
+});

package/src/options.ts

@@ -48,7 +48,10 @@ export const OptionsSchema = Joi.object({
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
         showSchemas: Joi.boolean(),
+        showInfoPage: Joi.boolean(),
+        schemasOnly: Joi.boolean(),
         disableCompression: Joi.boolean(),
+        maskCredentials: Joi.boolean(),
         version: Joi.string().when("versions", {
           is: Joi.exist(),
           then: Joi.required(),

package/src/plugin-openapi.d.ts

@@ -11,7 +11,7 @@ import type { FrontMatter as DocsFrontMatter } from "@docusaurus/types";
 import type { Props as DocsProps } from "@docusaurus/types";
 
 declare module "docusaurus-plugin-openapi-docs" {
-  import type { PropSidebars } from "@docusaurus/plugin-content-docs-types";
+  import type { PropSidebars } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 
   export type Options = Partial<import("./types").APIOptions>;
 

package/src/sidebars/index.ts

@@ -125,9 +125,21 @@ function groupByTags(
     apiTags = uniq(apiTags.concat(operationTags, schemaTags));
   }
 
-  const basePath = docPath
-    ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
-    : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
+  // Extract base path from outputDir, handling cases where docPath may not be in outputDir
+  const getBasePathFromOutput = (
+    output: string,
+    doc: string | undefined
+  ): string => {
+    if (doc && output.includes(doc)) {
+      return output.split(doc)[1]?.replace(/^\/+/g, "") ?? "";
+    }
+    const slashIndex = output.indexOf("/", 1);
+    return slashIndex === -1
+      ? ""
+      : output.slice(slashIndex).replace(/^\/+/g, "");
+  };
+
+  const basePath = getBasePathFromOutput(outputDir, docPath);
 
   const createDocItemFnContext = {
     sidebarOptions,

package/src/types.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import type { SidebarItemDoc } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 import Request from "postman-collection";
 
 import {
@@ -21,7 +21,7 @@ export type {
   SidebarItemLink,
   PropSidebar,
   PropSidebarItem,
-} from "@docusaurus/plugin-content-docs-types";
+} from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 export interface PluginOptions {
   id?: string;
   docsPlugin?: string;
@@ -51,7 +51,10 @@ export interface APIOptions {
   proxy?: string;
   markdownGenerators?: MarkdownGenerator;
   showSchemas?: boolean;
+  showInfoPage?: boolean;
+  schemasOnly?: boolean;
   disableCompression?: boolean;
+  maskCredentials?: boolean;
 }
 
 export interface MarkdownGenerator {

package/src/plugin-content-docs-types.d.ts

@@ -1,42 +0,0 @@
-/* ============================================================================
- * 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.
- * ========================================================================== */
-
-declare module "@docusaurus/plugin-content-docs-types" {
-  // Makes all properties visible when hovering over the type
-  type Expand<T extends Record<string, unknown>> = { [P in keyof T]: T[P] };
-
-  export type SidebarItemBase = {
-    className?: string;
-    customProps?: Record<string, unknown>;
-  };
-
-  export type SidebarItemLink = SidebarItemBase & {
-    type: "link";
-    href: string;
-    label: string;
-    docId: string;
-  };
-
-  type SidebarItemCategoryBase = SidebarItemBase & {
-    type: "category";
-    label: string;
-    collapsed: boolean;
-    collapsible: boolean;
-  };
-
-  export type PropSidebarItemCategory = Expand<
-    SidebarItemCategoryBase & {
-      items: PropSidebarItem[];
-    }
-  >;
-
-  export type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
-  export type PropSidebar = PropSidebarItem[];
-  export type PropSidebars = {
-    [sidebarId: string]: PropSidebar;
-  };
-}