feat: Add specInfoPagePath configuration option

- Add specInfoPagePath option to APIOptions interface
- Update createItems function to use specInfoPagePath if provided, falling back to kebab-cased info.title
- Update README with documentation for the new option
- Add comprehensive tests for the new configuration option

This allows users to customize the URL path of the info page independently from the title that is rendered on the page.

Author: omonk

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 {