docusaurus-plugin-openapi-docs 4.5.1 → 4.7.0

package/src/index.ts

@@ -21,6 +21,7 @@ import {
   createSchemaPageMD,
   createTagPageMD,
 } from "./markdown";
+import { ExternalFile, runWithExternalization } from "./markdown/utils";
 import { processOpenapiFiles, readOpenapiFiles } from "./openapi";
 import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
@@ -123,9 +124,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 +164,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 +238,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}}}
@@ -327,8 +334,24 @@ custom_edit_url: null
         if (downloadUrl) {
           item.downloadUrl = downloadUrl;
         }
-        const markdown = pageGeneratorByType[item.type](item as any);
-        item.markdown = markdown;
+
+        // Generate markdown, with externalization for API and schema pages
+        let externalFiles: ExternalFile[] = [];
+        if (
+          options.externalJsonProps &&
+          (item.type === "api" || item.type === "schema")
+        ) {
+          const result = runWithExternalization(item.id, () =>
+            pageGeneratorByType[item.type](item as any)
+          );
+          item.markdown = result.result;
+          externalFiles = result.files;
+        } else {
+          item.markdown = pageGeneratorByType[item.type](item as any);
+        }
+        if (isSchemasOnly && item.type !== "schema") {
+          return;
+        }
         if (item.type === "api") {
           // opportunity to compress JSON
           // const serialize = (o: any) => {
@@ -344,9 +367,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;
         }
@@ -365,6 +397,18 @@ custom_edit_url: null
                   "Operation must have summary or operationId defined"
                 );
               }
+
+              // Write externalized JSON files
+              for (const jsonFile of externalFiles) {
+                const jsonPath = `${outputDir}/${jsonFile.filename}`;
+                if (!fs.existsSync(jsonPath)) {
+                  fs.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                  console.log(
+                    chalk.green(`Successfully created "${jsonPath}"`)
+                  );
+                }
+              }
+
               fs.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
               console.log(
                 chalk.green(
@@ -452,6 +496,18 @@ custom_edit_url: null
               }
               // eslint-disable-next-line testing-library/render-result-naming-convention
               const schemaView = render(schemaMdTemplate, item);
+
+              // Write externalized JSON files in schemas directory
+              for (const jsonFile of externalFiles) {
+                const jsonPath = `${outputDir}/schemas/${jsonFile.filename}`;
+                if (!fs.existsSync(jsonPath)) {
+                  fs.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                  console.log(
+                    chalk.green(`Successfully created "${jsonPath}"`)
+                  );
+                }
+              }
+
               fs.writeFileSync(
                 `${outputDir}/schemas/${item.id}.schema.mdx`,
                 schemaView,
@@ -482,29 +538,74 @@ 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,
+      });
+      // Clean up externalized JSON files
+      const jsonFiles = await Globby(["*.json", "!versions.json"], {
+        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}"`)
+            );
+          }
+        })
+      );
+
+      // Clean up externalized JSON files
+      jsonFiles.map((jsonFile) =>
+        fs.unlink(`${apiDir}/${jsonFile}`, (err) => {
+          if (err) {
+            console.error(
+              chalk.red(`Cleanup failed for "${apiDir}/${jsonFile}"`),
+              chalk.yellow(err)
+            );
+          } else {
+            console.log(
+              chalk.green(`Cleanup succeeded for "${apiDir}/${jsonFile}"`)
+            );
+          }
+        })
+      );
+    }
 
     try {
       fs.rmSync(`${apiDir}/schemas`, { recursive: true });
@@ -517,21 +618,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 +718,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 +726,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 +753,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 +785,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 +797,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 +809,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 +825,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 +858,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 +890,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 +905,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 +923,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 +961,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 +983,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 +1023,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 +1041,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/markdown/schema.ts

@@ -8,6 +8,12 @@
 import { SchemaObject } from "../openapi/types";
 
 function prettyName(schema: SchemaObject, circular?: boolean) {
+  // Handle enum-only schemas (valid in JSON Schema)
+  // When enum is present without explicit type, treat as string
+  if (schema.enum && !schema.type) {
+    return "string";
+  }
+
   if (schema.format) {
     if (schema.type) {
       return `${schema.type}<${schema.format}>`;