docusaurus-plugin-openapi-docs 4.5.1 → 4.7.0

package/src/markdown/utils.ts

@@ -5,9 +5,93 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+/**
+ * Represents an external JSON file to be written alongside the MDX.
+ */
+export interface ExternalFile {
+  /** The filename for the JSON file (relative to outputDir) */
+  filename: string;
+  /** The JSON content to write */
+  content: string;
+}
+
+/**
+ * Result of running MDX generation with externalization.
+ */
+export interface ExternalizationResult<T> {
+  /** The result of the generation function */
+  result: T;
+  /** External JSON files to write */
+  files: ExternalFile[];
+}
+
+/**
+ * Context for externalization during MDX generation.
+ */
+interface ExternalizationContext {
+  /** Base filename for external files (e.g., "add-pet" for "add-pet.api.mdx") */
+  baseFilename: string;
+  /** Counter for generating unique filenames per component type */
+  componentCounters: Record<string, number>;
+  /** Collected external files during generation */
+  files: ExternalFile[];
+}
+
+/**
+ * Module-level externalization context.
+ * Note: AsyncLocalStorage would be cleaner but isn't available in browser bundles.
+ */
+let externalizationContext: ExternalizationContext | null = null;
+
+/**
+ * Components whose props should be externalized to separate JSON files.
+ * These are the components that typically receive large JSON objects.
+ */
+const EXTERNALIZABLE_COMPONENTS = new Set([
+  "StatusCodes",
+  "ParamsDetails",
+  "RequestSchema",
+  "Schema",
+  "SchemaItem",
+]);
+
+/**
+ * Runs a function with externalization enabled.
+ * Any calls to create() within the function will externalize eligible component props.
+ *
+ * @param baseFilename - Base filename for the MDX file (without extension)
+ * @param fn - Function to run with externalization enabled
+ * @returns The function result and any external files that were collected
+ *
+ * @example
+ * const { result: mdx, files } = runWithExternalization("add-pet", () => {
+ *   return createApiPageMD(item);
+ * });
+ */
+export function runWithExternalization<T>(
+  baseFilename: string,
+  fn: () => T
+): ExternalizationResult<T> {
+  // Set up context
+  externalizationContext = {
+    baseFilename,
+    componentCounters: {},
+    files: [],
+  };
+
+  try {
+    const result = fn();
+    const files = externalizationContext.files;
+    return { result, files };
+  } finally {
+    // Always clear context
+    externalizationContext = null;
+  }
+}
+
 /**
  * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
- * It is designed for rendering HTML a strings.
+ * It is designed for rendering HTML as strings.
  */
 export type Children = string | undefined | (string | string[] | undefined)[];
 
@@ -15,6 +99,11 @@ export type Props = Record<string, any> & { children?: Children };
 
 export type Options = { inline?: boolean };
 
+/**
+ * Creates a JSX component string with the given tag, props, and options.
+ * When called within runWithExternalization(), props for eligible
+ * components are externalized to a single JSON file and spread.
+ */
 export function create(
   tag: string,
   props: Props,
@@ -23,9 +112,27 @@ export function create(
   const { children, ...rest } = props;
 
   let propString = "";
-  for (const [key, value] of Object.entries(rest)) {
-    propString += `\n  ${key}={${JSON.stringify(value)}}`;
+
+  // Check if this component's props should be externalized
+  if (shouldExternalizeComponent(tag, rest)) {
+    const filename = generateExternalFilename(tag);
+    const content = JSON.stringify(rest);
+
+    // Add to external files
+    externalizationContext!.files.push({
+      filename,
+      content,
+    });
+
+    // Use spread syntax with require
+    propString = `\n  {...require("./${filename}")}`;
+  } else {
+    // Inline props as usual
+    for (const [key, value] of Object.entries(rest)) {
+      propString += `\n  ${key}={${JSON.stringify(value)}}`;
+    }
   }
+
   let indentedChildren = render(children).replace(/^/gm, "  ");
 
   if (options.inline) {
@@ -38,6 +145,49 @@ export function create(
   return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
 
+/**
+ * Determines if a component's props should be externalized.
+ */
+function shouldExternalizeComponent(
+  tag: string,
+  props: Record<string, any>
+): boolean {
+  // No context means externalization is not enabled
+  if (!externalizationContext) {
+    return false;
+  }
+
+  if (!EXTERNALIZABLE_COMPONENTS.has(tag)) {
+    return false;
+  }
+
+  // Don't externalize if props are empty or only contain undefined/null
+  const hasContent = Object.values(props).some(
+    (v) => v !== undefined && v !== null
+  );
+  if (!hasContent) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Generates a unique filename for an externalized component's props.
+ */
+function generateExternalFilename(componentName: string): string {
+  if (!externalizationContext) {
+    throw new Error("Externalization context not set");
+  }
+
+  const count =
+    (externalizationContext.componentCounters[componentName] ?? 0) + 1;
+  externalizationContext.componentCounters[componentName] = count;
+
+  const suffix = count > 1 ? `.${count}` : "";
+  return `${externalizationContext.baseFilename}.${componentName}${suffix}.json`;
+}
+
 export function guard<T>(
   value: T | undefined,
   cb: (value: T) => Children

package/src/openapi/__fixtures__/webhook/openapi.yaml

@@ -0,0 +1,17 @@
+openapi: 3.0.3
+info:
+  title: Webhook Example
+  version: 1.0.0
+paths: {}
+webhooks:
+  order.created:
+    post:
+      requestBody:
+        description: example body
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        "200":
+          description: OK

package/src/openapi/createSchemaExample.test.ts

@@ -0,0 +1,57 @@
+/* ============================================================================
+ * 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 { sampleFromSchema } from "./createSchemaExample";
+import { SchemaObject } from "./types";
+
+describe("sampleFromSchema", () => {
+  describe("const support", () => {
+    it("should return default string value when const is not present", () => {
+      const schema: SchemaObject = {
+        type: "string",
+      };
+      const context = { type: "request" as const };
+
+      const result = sampleFromSchema(schema, context);
+
+      expect(result).toBe("string");
+    });
+
+    it("should return const value when const is present", () => {
+      const schema: SchemaObject = {
+        type: "string",
+        const: "example",
+      };
+      const context = { type: "request" as const };
+
+      const result = sampleFromSchema(schema, context);
+
+      expect(result).toBe("example");
+    });
+
+    it("should handle anyOf with const values", () => {
+      const schema: SchemaObject = {
+        type: "string",
+        anyOf: [
+          {
+            type: "string",
+            const: "dog",
+          },
+          {
+            type: "string",
+            const: "cat",
+          },
+        ],
+      };
+      const context = { type: "request" as const };
+
+      const result = sampleFromSchema(schema, context);
+
+      expect(result).toBe("dog");
+    });
+  });
+});

package/src/openapi/createSchemaExample.ts

@@ -91,7 +91,12 @@ function sampleFromProp(
 
   // TODO: handle discriminators
 
-  if (prop.oneOf) {
+  // Check for explicit example/examples first (OAS 3.1 support)
+  if (prop.example !== undefined) {
+    obj[name] = prop.example;
+  } else if (prop.examples !== undefined && prop.examples.length > 0) {
+    obj[name] = prop.examples[0];
+  } else if (prop.oneOf) {
     obj[name] = sampleFromSchema(prop.oneOf[0], context);
   } else if (prop.anyOf) {
     obj[name] = sampleFromSchema(prop.anyOf[0], context);
@@ -111,12 +116,27 @@ export const sampleFromSchema = (
   try {
     // deep copy schema before processing
     let schemaCopy = JSON.parse(JSON.stringify(schema));
-    let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
+    let {
+      type,
+      example,
+      examples,
+      allOf,
+      properties,
+      items,
+      oneOf,
+      anyOf,
+      const: constant,
+    } = schemaCopy;
 
     if (example !== undefined) {
       return example;
     }
 
+    // OAS 3.1 / JSON Schema: examples is an array
+    if (examples !== undefined && examples.length > 0) {
+      return examples[0];
+    }
+
     if (oneOf) {
       if (properties) {
         const combinedSchemas = merge(schemaCopy, oneOf[0]);
@@ -218,6 +238,10 @@ export const sampleFromSchema = (
       return undefined;
     }
 
+    if (constant) {
+      return constant;
+    }
+
     return primitive(schemaCopy);
   } catch (err) {
     console.error(

package/src/openapi/openapi.test.ts

@@ -11,6 +11,8 @@ import path from "path";
 import { posixPath } from "@docusaurus/utils";
 
 import { readOpenapiFiles } from ".";
+import { processOpenapiFile } from "./openapi";
+import type { APIOptions, SidebarOptions } from "../types";
 
 // npx jest packages/docusaurus-plugin-openapi/src/openapi/openapi.test.ts --watch
 
@@ -37,4 +39,60 @@ describe("openapi", () => {
       ).toBeDefined();
     });
   });
+
+  describe("schemasOnly", () => {
+    it("includes schema metadata when showSchemas is disabled", async () => {
+      const openapiData = {
+        openapi: "3.0.0",
+        info: {
+          title: "Schema Only",
+          version: "1.0.0",
+        },
+        paths: {
+          "/ping": {
+            get: {
+              summary: "Ping",
+              responses: {
+                "200": {
+                  description: "OK",
+                },
+              },
+            },
+          },
+        },
+        components: {
+          schemas: {
+            WithoutTags: {
+              title: "Without Tags",
+              type: "object",
+              properties: {
+                value: {
+                  type: "string",
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const options: APIOptions = {
+        specPath: "dummy", // required by the type but unused in this context
+        outputDir: "build",
+        showSchemas: false,
+        schemasOnly: true,
+      };
+
+      const sidebarOptions = {} as SidebarOptions;
+
+      const [items] = await processOpenapiFile(
+        openapiData as any,
+        options,
+        sidebarOptions
+      );
+
+      const schemaItems = items.filter((item) => item.type === "schema");
+      expect(schemaItems).toHaveLength(1);
+      expect(schemaItems[0].id).toBe("without-tags");
+    });
+  });
 });

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,11 @@ export const OptionsSchema = Joi.object({
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
         showSchemas: Joi.boolean(),
+        showInfoPage: Joi.boolean(),
+        schemasOnly: Joi.boolean(),
         disableCompression: Joi.boolean(),
+        maskCredentials: Joi.boolean(),
+        externalJsonProps: Joi.boolean().default(true),
         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 → types.d.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,17 @@ export interface APIOptions {
   proxy?: string;
   markdownGenerators?: MarkdownGenerator;
   showSchemas?: boolean;
+  showInfoPage?: boolean;
+  schemasOnly?: boolean;
   disableCompression?: boolean;
+  maskCredentials?: boolean;
+  /**
+   * When enabled, large JSON props in generated MDX are written to external
+   * files and loaded via require(). This can significantly improve MDX
+   * compilation performance for large OpenAPI specs.
+   * @see https://github.com/facebook/docusaurus/discussions/11664
+   */
+  externalJsonProps?: boolean;
 }
 
 export interface MarkdownGenerator {