docusaurus-plugin-openapi-docs 0.0.0-1075 → 0.0.0-1077

package/README.md

@@ -328,6 +328,16 @@ yarn docusaurus gen-api-docs all --all-versions
 
 > This will generate API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
 
+To generate only schema MDX files—without updating the sidebar or requiring `showSchemas` in your plugin config—use the `--schemas-only` flag:
+
+```bash
+yarn docusaurus gen-api-docs petstore --schemas-only
+```
+
+> This command writes the schema pages to the configured output directory while leaving other generated docs untouched.
+
+The `--schemas-only` flag is also available for `gen-api-docs:version`.
+
 ### Cleaning API Docs
 
 To clean/remove all API Docs, run the following command from the root directory of your project:
@@ -360,6 +370,14 @@ yarn docusaurus clean-api-docs all --all-versions
 
 > This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
 
+To clean only schema docs while leaving API, info, and tag docs untouched, use the `--schemas-only` flag:
+
+```bash
+yarn docusaurus clean-api-docs petstore --schemas-only
+```
+
+> The `--schemas-only` flag is also available for `clean-api-docs:version`.
+
 ### Versioning OpenAPI docs
 
 To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

package/lib/index.js

@@ -78,7 +78,8 @@ function pluginOpenAPIDocs(context, options) {
     let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options, pluginId) {
         var _a, _b, _c, _d;
-        let { specPath, outputDir, template, infoTemplate, tagTemplate, schemaTemplate, markdownGenerators, downloadUrl, sidebarOptions, disableCompression, } = options;
+        let { specPath, outputDir, template, infoTemplate, tagTemplate, schemaTemplate, markdownGenerators, downloadUrl, sidebarOptions, schemasOnly, disableCompression, } = options;
+        const isSchemasOnly = schemasOnly === true;
         // Remove trailing slash before proceeding
         outputDir = outputDir.replace(/\/$/, "");
         // Override docPath if pluginId provided
@@ -103,7 +104,7 @@ function pluginOpenAPIDocs(context, options) {
                 }
             }
             // TODO: figure out better way to set default
-            if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
+            if (!isSchemasOnly && Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
                 const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath, tagGroups);
                 let sidebarSliceTemplate = `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";\n\n`;
                 sidebarSliceTemplate += `const sidebar: SidebarsConfig = {{{slice}}};\n\n`;
@@ -238,6 +239,9 @@ custom_edit_url: null
                 }
                 const markdown = pageGeneratorByType[item.type](item);
                 item.markdown = markdown;
+                if (isSchemasOnly && item.type !== "schema") {
+                    return;
+                }
                 if (item.type === "api") {
                     // opportunity to compress JSON
                     // const serialize = (o: any) => {
@@ -338,25 +342,36 @@ custom_edit_url: null
             throw e;
         }
     }
-    async function cleanApiDocs(options) {
+    async function cleanApiDocs(options, schemasOnly = false) {
         const { outputDir } = options;
         const apiDir = (0, utils_1.posixPath)(path_1.default.join(siteDir, outputDir));
-        const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
-            cwd: path_1.default.resolve(apiDir),
-            deep: 1,
-        });
-        const sidebarFile = await (0, utils_1.Globby)(["sidebar.js", "sidebar.ts"], {
-            cwd: path_1.default.resolve(apiDir),
-            deep: 1,
-        });
-        apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
-            if (err) {
-                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${mdx}"`), chalk_1.default.yellow(err));
-            }
-            else {
-                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
-            }
-        }));
+        // When schemasOnly is true, only clean the schemas directory
+        if (!schemasOnly) {
+            const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
+                cwd: path_1.default.resolve(apiDir),
+                deep: 1,
+            });
+            const sidebarFile = await (0, utils_1.Globby)(["sidebar.js", "sidebar.ts"], {
+                cwd: path_1.default.resolve(apiDir),
+                deep: 1,
+            });
+            apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${mdx}"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
+                }
+            }));
+            sidebarFile.map((sidebar) => fs_1.default.unlink(`${apiDir}/${sidebar}`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${sidebar}"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`));
+                }
+            }));
+        }
         try {
             fs_1.default.rmSync(`${apiDir}/schemas`, { recursive: true });
             console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/schemas"`));
@@ -366,14 +381,6 @@ custom_edit_url: null
                 console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/schemas"`), chalk_1.default.yellow(err));
             }
         }
-        sidebarFile.map((sidebar) => fs_1.default.unlink(`${apiDir}/${sidebar}`, (err) => {
-            if (err) {
-                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${sidebar}"`), chalk_1.default.yellow(err));
-            }
-            else {
-                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`));
-            }
-        }));
     }
     async function generateVersions(versions, outputDir) {
         let versionsArray = [];
@@ -445,19 +452,21 @@ custom_edit_url: null
             });
         }
     }
-    async function cleanAllVersions(options) {
+    async function cleanAllVersions(options, schemasOnly = false) {
         const parentOptions = Object.assign({}, options);
         const { versions } = parentOptions;
         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);
             });
         }
     }
@@ -471,11 +480,13 @@ 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) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
                 const allVersions = options.allVersions;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 let targetDocsPluginId;
@@ -497,15 +508,17 @@ custom_edit_url: null
                     }
                     targetConfig = config;
                 }
+                const withSchemaOverride = (apiOptions) => schemasOnly ? { ...apiOptions, schemasOnly: true } : apiOptions;
                 if (id === "all") {
                     if (targetConfig[id]) {
                         console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs configuration key."));
                     }
                     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);
                             }
                         });
                     }
@@ -514,9 +527,10 @@ custom_edit_url: null
                     console.error(chalk_1.default.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);
                     }
                 }
             });
@@ -526,10 +540,12 @@ 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) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 let targetDocsPluginId;
@@ -553,6 +569,7 @@ custom_edit_url: null
                 }
                 const [parentId, versionId] = id.split(":");
                 const parentConfig = Object.assign({}, targetConfig[parentId]);
+                const withSchemaOverride = (apiOptions) => schemasOnly ? { ...apiOptions, schemasOnly: true } : apiOptions;
                 const version = parentConfig.version;
                 const label = parentConfig.label;
                 const baseUrl = parentConfig.baseUrl;
@@ -575,10 +592,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);
                         });
                     }
@@ -588,10 +605,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);
                 }
@@ -603,11 +620,13 @@ 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) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
                 const allVersions = options.allVersions;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 if (pluginId) {
@@ -633,17 +652,17 @@ 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);
                     }
                 }
             });
@@ -653,10 +672,12 @@ 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) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 if (pluginId) {
@@ -685,14 +706,16 @@ custom_edit_url: null
                         chalk_1.default.red("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);
                         });
                     }
                 }
@@ -702,7 +725,7 @@ custom_edit_url: null
                         ...parentConfig,
                         ...versionConfig,
                     };
-                    await cleanApiDocs(mergedConfig);
+                    await cleanApiDocs(mergedConfig, schemasOnly);
                 }
             });
         },

package/lib/openapi/openapi.js

@@ -108,6 +108,7 @@ function createItems(openapiData, options, sidebarOptions) {
     let items = [];
     const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
     const infoId = (0, kebabCase_1.default)(infoIdSpaces);
+    const schemasOnly = (options === null || options === void 0 ? void 0 : options.schemasOnly) === true;
     if (openapiData.info.description || openapiData.info.title) {
         // Only create an info page if we have a description.
         const infoDescription = (_a = openapiData.info) === null || _a === void 0 ? void 0 : _a.description;
@@ -378,13 +379,16 @@ function createItems(openapiData, options, sidebarOptions) {
             items.push(apiPage);
         }
     }
-    if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
+    if (schemasOnly ||
+        (options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
         Object.entries((_3 = (_2 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _2 === void 0 ? void 0 : _2.schemas) !== null && _3 !== void 0 ? _3 : {})
             .flatMap(([_, s]) => s["x-tags"])
             .filter((item) => !!item).length > 0) {
         // Gather schemas
         for (let [schema, schemaObject] of Object.entries((_5 = (_4 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _4 === void 0 ? void 0 : _4.schemas) !== null && _5 !== void 0 ? _5 : {})) {
-            if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true || schemaObject["x-tags"]) {
+            if (schemasOnly ||
+                (options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
+                schemaObject["x-tags"]) {
                 const baseIdSpaces = (_7 = (_6 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _6 === void 0 ? void 0 : _6.replace(" ", "-").toLowerCase()) !== null && _7 !== void 0 ? _7 : "";
                 const baseId = (0, kebabCase_1.default)(baseIdSpaces);
                 const schemaDescription = schemaObject.description;

package/lib/openapi/openapi.test.js

@@ -13,6 +13,7 @@ const path_1 = __importDefault(require("path"));
 // eslint-disable-next-line import/no-extraneous-dependencies
 const utils_1 = require("@docusaurus/utils");
 const _1 = require(".");
+const openapi_1 = require("./openapi");
 // npx jest packages/docusaurus-plugin-openapi/src/openapi/openapi.test.ts --watch
 describe("openapi", () => {
     describe("readOpenapiFiles", () => {
@@ -30,4 +31,51 @@ describe("openapi", () => {
             expect((_b = (_a = yaml === null || yaml === void 0 ? void 0 : yaml.data.components) === null || _a === void 0 ? void 0 : _a.schemas) === null || _b === void 0 ? void 0 : _b.HelloString["x-tags"]).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 = {
+                specPath: "dummy", // required by the type but unused in this context
+                outputDir: "build",
+                showSchemas: false,
+                schemasOnly: true,
+            };
+            const sidebarOptions = {};
+            const [items] = await (0, openapi_1.processOpenapiFile)(openapiData, options, sidebarOptions);
+            const schemaItems = items.filter((item) => item.type === "schema");
+            expect(schemaItems).toHaveLength(1);
+            expect(schemaItems[0].id).toBe("without-tags");
+        });
+    });
 });

package/lib/types.d.ts

@@ -29,6 +29,7 @@ export interface APIOptions {
     proxy?: string;
     markdownGenerators?: MarkdownGenerator;
     showSchemas?: boolean;
+    schemasOnly?: boolean;
     disableCompression?: boolean;
     maskCredentials?: boolean;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-1075",
+  "version": "0.0.0-1077",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "d4ec26e753c5bab96246a39a07b4ccd5a5ae8344"
+  "gitHead": "9a7f0853967fa5b5e0241a48f65f36e1f7d3d591"
 }

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,
@@ -332,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) => {
@@ -485,29 +491,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 });
@@ -520,21 +550,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) {
@@ -635,7 +650,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;
@@ -643,14 +658,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);
       });
     }
   }
@@ -668,10 +685,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;
@@ -698,6 +717,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(
@@ -707,12 +729,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);
                 }
               });
             }
@@ -721,9 +741,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);
             }
           }
         });
@@ -736,9 +757,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;
@@ -767,6 +790,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;
@@ -796,10 +822,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);
               });
             }
@@ -811,10 +837,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);
           }
@@ -829,10 +855,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) {
@@ -865,16 +893,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);
             }
           }
         });
@@ -887,9 +915,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) {
@@ -925,14 +955,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 {
@@ -941,7 +973,7 @@ custom_edit_url: null
               ...parentConfig,
               ...versionConfig,
             };
-            await cleanApiDocs(mergedConfig);
+            await cleanApiDocs(mergedConfig, schemasOnly);
           }
         });
     },

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

@@ -95,6 +95,7 @@ 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.
@@ -434,6 +435,7 @@ function createItems(
   }
 
   if (
+    schemasOnly ||
     options?.showSchemas === true ||
     Object.entries(openapiData?.components?.schemas ?? {})
       .flatMap(([_, s]) => s["x-tags"])
@@ -443,7 +445,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/types.ts

@@ -51,6 +51,7 @@ export interface APIOptions {
   proxy?: string;
   markdownGenerators?: MarkdownGenerator;
   showSchemas?: boolean;
+  schemasOnly?: boolean;
   disableCompression?: boolean;
   maskCredentials?: boolean;
 }