docusaurus-plugin-openapi-docs 4.5.0 → 4.6.0

package/src/index.ts

@@ -123,9 +123,12 @@ export default function pluginOpenAPIDocs(
       markdownGenerators,
       downloadUrl,
       sidebarOptions,
+      schemasOnly,
       disableCompression,
     } = options;
 
+    const isSchemasOnly = schemasOnly === true;
+
     // Remove trailing slash before proceeding
     outputDir = outputDir.replace(/\/$/, "");
 
@@ -160,7 +163,7 @@ export default function pluginOpenAPIDocs(
       }
 
       // TODO: figure out better way to set default
-      if (Object.keys(sidebarOptions ?? {}).length > 0) {
+      if (!isSchemasOnly && Object.keys(sidebarOptions ?? {}).length > 0) {
         const sidebarSlice = generateSidebarSlice(
           sidebarOptions!,
           options,
@@ -234,6 +237,9 @@ hide_send_button: true
 {{#frontMatter.show_extensions}}
 show_extensions: true
 {{/frontMatter.show_extensions}}
+{{#frontMatter.mask_credentials_disabled}}
+mask_credentials: false
+{{/frontMatter.mask_credentials_disabled}}
 ---
 
 {{{markdown}}}
@@ -329,6 +335,9 @@ custom_edit_url: null
         }
         const markdown = pageGeneratorByType[item.type](item as any);
         item.markdown = markdown;
+        if (isSchemasOnly && item.type !== "schema") {
+          return;
+        }
         if (item.type === "api") {
           // opportunity to compress JSON
           // const serialize = (o: any) => {
@@ -344,9 +353,18 @@ custom_edit_url: null
                 .toString("base64"));
           let infoBasePath = `${outputDir}/${item.infoId}`;
           if (docRouteBasePath) {
-            infoBasePath = `${docRouteBasePath}/${outputDir
-              .split(docPath!)[1]
-              .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+            // Safely extract path segment, handling cases where docPath may not be in outputDir
+            const outputSegment =
+              docPath && outputDir.includes(docPath)
+                ? (outputDir.split(docPath)[1]?.replace(/^\/+/g, "") ?? "")
+                : outputDir
+                    .slice(outputDir.indexOf("/", 1))
+                    .replace(/^\/+/g, "");
+            infoBasePath =
+              `${docRouteBasePath}/${outputSegment}/${item.infoId}`.replace(
+                /^\/+/g,
+                ""
+              );
           }
           if (item.infoId) item.infoPath = infoBasePath;
         }
@@ -482,29 +500,53 @@ custom_edit_url: null
     }
   }
 
-  async function cleanApiDocs(options: APIOptions) {
+  async function cleanApiDocs(options: APIOptions, schemasOnly = false) {
     const { outputDir } = options;
     const apiDir = posixPath(path.join(siteDir, outputDir));
-    const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
-      cwd: path.resolve(apiDir),
-      deep: 1,
-    });
-    const sidebarFile = await Globby(["sidebar.js", "sidebar.ts"], {
-      cwd: path.resolve(apiDir),
-      deep: 1,
-    });
-    apiMdxFiles.map((mdx) =>
-      fs.unlink(`${apiDir}/${mdx}`, (err) => {
-        if (err) {
-          console.error(
-            chalk.red(`Cleanup failed for "${apiDir}/${mdx}"`),
-            chalk.yellow(err)
-          );
-        } else {
-          console.log(chalk.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
+
+    // When schemasOnly is true, only clean the schemas directory
+    if (!schemasOnly) {
+      const apiMdxFiles = await Globby(
+        ["*.api.mdx", "*.info.mdx", "*.tag.mdx"],
+        {
+          cwd: path.resolve(apiDir),
+          deep: 1,
         }
-      })
-    );
+      );
+      const sidebarFile = await Globby(["sidebar.js", "sidebar.ts"], {
+        cwd: path.resolve(apiDir),
+        deep: 1,
+      });
+      apiMdxFiles.map((mdx) =>
+        fs.unlink(`${apiDir}/${mdx}`, (err) => {
+          if (err) {
+            console.error(
+              chalk.red(`Cleanup failed for "${apiDir}/${mdx}"`),
+              chalk.yellow(err)
+            );
+          } else {
+            console.log(
+              chalk.green(`Cleanup succeeded for "${apiDir}/${mdx}"`)
+            );
+          }
+        })
+      );
+
+      sidebarFile.map((sidebar) =>
+        fs.unlink(`${apiDir}/${sidebar}`, (err) => {
+          if (err) {
+            console.error(
+              chalk.red(`Cleanup failed for "${apiDir}/${sidebar}"`),
+              chalk.yellow(err)
+            );
+          } else {
+            console.log(
+              chalk.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`)
+            );
+          }
+        })
+      );
+    }
 
     try {
       fs.rmSync(`${apiDir}/schemas`, { recursive: true });
@@ -517,21 +559,6 @@ custom_edit_url: null
         );
       }
     }
-
-    sidebarFile.map((sidebar) =>
-      fs.unlink(`${apiDir}/${sidebar}`, (err) => {
-        if (err) {
-          console.error(
-            chalk.red(`Cleanup failed for "${apiDir}/${sidebar}"`),
-            chalk.yellow(err)
-          );
-        } else {
-          console.log(
-            chalk.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`)
-          );
-        }
-      })
-    );
   }
 
   async function generateVersions(versions: object, outputDir: string) {
@@ -632,7 +659,7 @@ custom_edit_url: null
     }
   }
 
-  async function cleanAllVersions(options: APIOptions) {
+  async function cleanAllVersions(options: APIOptions, schemasOnly = false) {
     const parentOptions = Object.assign({}, options);
 
     const { versions } = parentOptions as any;
@@ -640,14 +667,16 @@ custom_edit_url: null
     delete parentOptions.versions;
 
     if (versions != null && Object.keys(versions).length > 0) {
-      await cleanVersions(parentOptions.outputDir);
+      if (!schemasOnly) {
+        await cleanVersions(parentOptions.outputDir);
+      }
       Object.keys(versions).forEach(async (key) => {
         const versionOptions = versions[key];
         const mergedOptions = {
           ...parentOptions,
           ...versionOptions,
         };
-        await cleanApiDocs(mergedOptions);
+        await cleanApiDocs(mergedOptions, schemasOnly);
       });
     }
   }
@@ -665,10 +694,12 @@ custom_edit_url: null
         .arguments("<id>")
         .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
         .option("--all-versions", "Generate all versions.")
+        .option("--schemas-only", "Generate only schema docs.")
         .action(async (id, instance) => {
           const options = instance.opts();
           const pluginId = options.pluginId;
           const allVersions = options.allVersions;
+          const schemasOnly = options.schemasOnly;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
           let targetDocsPluginId: any;
@@ -695,6 +726,9 @@ custom_edit_url: null
             targetConfig = config;
           }
 
+          const withSchemaOverride = (apiOptions: APIOptions): APIOptions =>
+            schemasOnly ? { ...apiOptions, schemasOnly: true } : apiOptions;
+
           if (id === "all") {
             if (targetConfig[id]) {
               console.error(
@@ -704,12 +738,10 @@ custom_edit_url: null
               );
             } else {
               Object.keys(targetConfig).forEach(async function (key) {
-                await generateApiDocs(targetConfig[key], targetDocsPluginId);
+                const apiOptions = withSchemaOverride(targetConfig[key]);
+                await generateApiDocs(apiOptions, targetDocsPluginId);
                 if (allVersions) {
-                  await generateAllVersions(
-                    targetConfig[key],
-                    targetDocsPluginId
-                  );
+                  await generateAllVersions(apiOptions, targetDocsPluginId);
                 }
               });
             }
@@ -718,9 +750,10 @@ custom_edit_url: null
               chalk.red(`ID '${id}' does not exist in OpenAPI docs config.`)
             );
           } else {
-            await generateApiDocs(targetConfig[id], targetDocsPluginId);
+            const apiOptions = withSchemaOverride(targetConfig[id]);
+            await generateApiDocs(apiOptions, targetDocsPluginId);
             if (allVersions) {
-              await generateAllVersions(targetConfig[id], targetDocsPluginId);
+              await generateAllVersions(apiOptions, targetDocsPluginId);
             }
           }
         });
@@ -733,9 +766,11 @@ custom_edit_url: null
         .usage("<id:version>")
         .arguments("<id:version>")
         .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .option("--schemas-only", "Generate only schema docs.")
         .action(async (id, instance) => {
           const options = instance.opts();
           const pluginId = options.pluginId;
+          const schemasOnly = options.schemasOnly;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
           let targetDocsPluginId: any;
@@ -764,6 +799,9 @@ custom_edit_url: null
           const [parentId, versionId] = id.split(":");
           const parentConfig = Object.assign({}, targetConfig[parentId]);
 
+          const withSchemaOverride = (apiOptions: APIOptions): APIOptions =>
+            schemasOnly ? { ...apiOptions, schemasOnly: true } : apiOptions;
+
           const version = parentConfig.version as string;
           const label = parentConfig.label as string;
           const baseUrl = parentConfig.baseUrl as string;
@@ -793,10 +831,10 @@ custom_edit_url: null
               await generateVersions(mergedVersions, parentConfig.outputDir);
               Object.keys(versions).forEach(async (key) => {
                 const versionConfig = versions[key];
-                const mergedConfig = {
+                const mergedConfig = withSchemaOverride({
                   ...parentConfig,
                   ...versionConfig,
-                };
+                });
                 await generateApiDocs(mergedConfig, targetDocsPluginId);
               });
             }
@@ -808,10 +846,10 @@ custom_edit_url: null
             );
           } else {
             const versionConfig = versions[versionId];
-            const mergedConfig = {
+            const mergedConfig = withSchemaOverride({
               ...parentConfig,
               ...versionConfig,
-            };
+            });
             await generateVersions(mergedVersions, parentConfig.outputDir);
             await generateApiDocs(mergedConfig, targetDocsPluginId);
           }
@@ -826,10 +864,12 @@ custom_edit_url: null
         .arguments("<id>")
         .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
         .option("--all-versions", "Clean all versions.")
+        .option("--schemas-only", "Clean only schema docs.")
         .action(async (id, instance) => {
           const options = instance.opts();
           const pluginId = options.pluginId;
           const allVersions = options.allVersions;
+          const schemasOnly = options.schemasOnly;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
           if (pluginId) {
@@ -862,16 +902,16 @@ custom_edit_url: null
               );
             } else {
               Object.keys(targetConfig).forEach(async function (key) {
-                await cleanApiDocs(targetConfig[key]);
+                await cleanApiDocs(targetConfig[key], schemasOnly);
                 if (allVersions) {
-                  await cleanAllVersions(targetConfig[key]);
+                  await cleanAllVersions(targetConfig[key], schemasOnly);
                 }
               });
             }
           } else {
-            await cleanApiDocs(targetConfig[id]);
+            await cleanApiDocs(targetConfig[id], schemasOnly);
             if (allVersions) {
-              await cleanAllVersions(targetConfig[id]);
+              await cleanAllVersions(targetConfig[id], schemasOnly);
             }
           }
         });
@@ -884,9 +924,11 @@ custom_edit_url: null
         .usage("<id:version>")
         .arguments("<id:version>")
         .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+        .option("--schemas-only", "Clean only schema docs.")
         .action(async (id, instance) => {
           const options = instance.opts();
           const pluginId = options.pluginId;
+          const schemasOnly = options.schemasOnly;
           const pluginInstances = getPluginInstances(plugins);
           let targetConfig: any;
           if (pluginId) {
@@ -922,14 +964,16 @@ custom_edit_url: null
                 "Can't use id 'all' for OpenAPI docs versions configuration key."
               );
             } else {
-              await cleanVersions(parentConfig.outputDir);
+              if (!schemasOnly) {
+                await cleanVersions(parentConfig.outputDir);
+              }
               Object.keys(versions).forEach(async (key) => {
                 const versionConfig = versions[key];
                 const mergedConfig = {
                   ...parentConfig,
                   ...versionConfig,
                 };
-                await cleanApiDocs(mergedConfig);
+                await cleanApiDocs(mergedConfig, schemasOnly);
               });
             }
           } else {
@@ -938,7 +982,7 @@ custom_edit_url: null
               ...parentConfig,
               ...versionConfig,
             };
-            await cleanApiDocs(mergedConfig);
+            await cleanApiDocs(mergedConfig, schemasOnly);
           }
         });
     },

package/src/markdown/createHeading.ts

@@ -5,14 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { clean, create } from "./utils";
+import { create } from "./utils";
 
 export function createHeading(heading: string) {
   return [
     create(
       "Heading",
       {
-        children: clean(heading),
+        children: heading,
         as: "h1",
         className: "openapi__heading",
       },

package/src/markdown/createRequestHeader.ts

@@ -9,16 +9,14 @@ import { create } from "./utils";
 
 export function createRequestHeader(header: string) {
   return [
-    create(
-      "Heading",
-      {
-        children: header,
-        id: header.replace(" ", "-").toLowerCase(),
-        as: "h2",
-        className: "openapi-tabs__heading",
-      },
-      { inline: true }
-    ),
-    `\n\n`,
+    create("Heading", {
+      id: header.replace(" ", "-").toLowerCase(),
+      as: "h2",
+      className: "openapi-tabs__heading",
+      children: [
+        `<Translate id="theme.openapi.request.title">${header}</Translate>`,
+      ],
+    }),
+    "\n\n",
   ];
 }

package/src/markdown/createSchema.ts

@@ -375,7 +375,8 @@ function createDetailsNode(
                     () => [
                       create("span", {
                         className: "openapi-schema__required",
-                        children: "required",
+                        children:
+                          "<Translate id='theme.openapi.schemaItem.required'>required</Translate>",
                       }),
                     ]
                   ),
@@ -530,7 +531,8 @@ function createPropertyDiscriminator(
             guard(required, () => [
               create("span", {
                 className: "openapi-schema__required",
-                children: "required",
+                children:
+                  "<Translate id='theme.openapi.schemaItem.required'>required</Translate>",
               }),
             ]),
           ],

package/src/markdown/index.ts

@@ -72,7 +72,8 @@ export function createApiPageMD({
     `import StatusCodes from "@theme/StatusCodes";\n`,
     `import OperationTabs from "@theme/OperationTabs";\n`,
     `import TabItem from "@theme/TabItem";\n`,
-    `import Heading from "@theme/Heading";\n\n`,
+    `import Heading from "@theme/Heading";\n`,
+    `import Translate from "@docusaurus/Translate";\n\n`,
     createHeading(title),
     createMethodEndpoint(method, path),
     infoPath && createAuthorization(infoPath),
@@ -134,7 +135,7 @@ export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
   return render([
     `import Schema from "@theme/Schema";\n`,
     `import Heading from "@theme/Heading";\n\n`,
-    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createHeading(title),
     createDescription(description),
     create("Schema", {
       schema: schema,

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");
+    });
+  });
 });