feat: Add specInfoPagePath configuration option

packages/docusaurus-plugin-openapi-docs/README.md

@@ -179,6 +179,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `showInfoPage`       | `boolean` | `true`  | _Optional:_ If set to `false`, disables generation of the info page (overview page with API title and description).                                            |
 | `schemasOnly`        | `boolean` | `false` | _Optional:_ If set to `true`, generates only schema pages (no API endpoint pages). Also available as `--schemas-only` CLI flag.                                |
 | `externalJsonProps`  | `boolean` | `true`  | _Optional:_ If set to `false`, disables externalization of large JSON props. By default, large JSON is written to external files for better build performance. |
+| `specInfoPagePath`   | `string`  | `null`  | _Optional:_ The path the root information page will be rendered at. Defaults to kebab case `info.title`.                                                       |
 
 ### sidebarOptions
 

packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.test.ts

@@ -95,4 +95,95 @@ describe("openapi", () => {
       expect(schemaItems[0].id).toBe("without-tags");
     });
   });
+
+  describe("specInfoPagePath", () => {
+    it("uses default kebab-cased info.title when specInfoPagePath is not provided", async () => {
+      const openapiData = {
+        openapi: "3.0.0",
+        info: {
+          title: "Company Foo",
+          version: "1.0.0",
+          description: "Test API",
+        },
+        paths: {},
+      };
+
+      const options: APIOptions = {
+        specPath: "dummy",
+        outputDir: "build",
+      };
+
+      const sidebarOptions = {} as SidebarOptions;
+
+      const [items] = await processOpenapiFile(
+        openapiData as any,
+        options,
+        sidebarOptions
+      );
+
+      const infoItem = items.find((item) => item.type === "info");
+      expect(infoItem).toBeDefined();
+      expect(infoItem?.id).toBe("company-foo");
+    });
+
+    it("uses custom specInfoPagePath when provided", async () => {
+      const openapiData = {
+        openapi: "3.0.0",
+        info: {
+          title: "Company Foo",
+          version: "1.0.0",
+          description: "Test API",
+        },
+        paths: {},
+      };
+
+      const options: APIOptions = {
+        specPath: "dummy",
+        outputDir: "build",
+        specInfoPagePath: "custom-api-intro",
+      };
+
+      const sidebarOptions = {} as SidebarOptions;
+
+      const [items] = await processOpenapiFile(
+        openapiData as any,
+        options,
+        sidebarOptions
+      );
+
+      const infoItem = items.find((item) => item.type === "info");
+      expect(infoItem).toBeDefined();
+      expect(infoItem?.id).toBe("custom-api-intro");
+    });
+
+    it("kebab-cases custom specInfoPagePath", async () => {
+      const openapiData = {
+        openapi: "3.0.0",
+        info: {
+          title: "Company Foo",
+          version: "1.0.0",
+          description: "Test API",
+        },
+        paths: {},
+      };
+
+      const options: APIOptions = {
+        specPath: "dummy",
+        outputDir: "build",
+        specInfoPagePath: "Custom API Introduction",
+      };
+
+      const sidebarOptions = {} as SidebarOptions;
+
+      const [items] = await processOpenapiFile(
+        openapiData as any,
+        options,
+        sidebarOptions
+      );
+
+      const infoItem = items.find((item) => item.type === "info");
+      expect(infoItem).toBeDefined();
+      expect(infoItem?.id).toBe("custom-api-introduction");
+    });
+  });
 });

packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts

@@ -94,7 +94,7 @@ function createItems(
   // TODO: Find a better way to handle this
   let items: PartialPage<ApiMetadata>[] = [];
   const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
-  const infoId = kebabCase(infoIdSpaces);
+  const infoId = kebabCase(options?.specInfoPagePath ?? infoIdSpaces);
   const schemasOnly = options?.schemasOnly === true;
 
   // Only create an info page if we have a description/title AND showInfoPage is not false

packages/docusaurus-plugin-openapi-docs/src/types.d.ts

@@ -62,6 +62,11 @@ export interface APIOptions {
    * @see https://github.com/facebook/docusaurus/discussions/11664
    */
   externalJsonProps?: boolean;
+  /**
+   * The path the root information page will be rendered at.
+   * Defaults to kebab case info.title
+   */
+  specInfoPagePath?: string;
 }
 
 export interface MarkdownGenerator {