docusaurus-plugin-openapi-docs 0.0.0-827 → 0.0.0-833

package/README.md

@@ -181,6 +181,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `sidebarGenerators`  | `object`  | `null`  | Optional: Customize sidebar rendering with callback functions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 > You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
 
@@ -206,6 +207,14 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `createTagPageMD`    | `function` | `null`  | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string`       |
 | `createSchemaPageMD` | `function` | `null`  | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `(pageData: SchemaPageMetadata) => string` |
 
+### sidebarGenerators
+
+`sidebarGenerators` can be configured with the following options:
+
+| Name            | Type       | Default | Description                                                                                                                                                                                                                                      |
+| --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createDocItem` | `function` | `null`  | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.<br/><br/>**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
+
 ## CLI Usage
 
 ```bash

package/lib/options.js

@@ -8,12 +8,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const sidebarGenerators = utils_validation_1.Joi.object({
+    createDocItem: utils_validation_1.Joi.function(),
+});
 const sidebarOptions = utils_validation_1.Joi.object({
     groupPathsBy: utils_validation_1.Joi.string().valid("tag", "tagGroup"),
     categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info", "auto"),
     customProps: utils_validation_1.Joi.object(),
     sidebarCollapsible: utils_validation_1.Joi.boolean(),
     sidebarCollapsed: utils_validation_1.Joi.boolean(),
+    sidebarGenerators: sidebarGenerators,
 });
 const markdownGenerators = utils_validation_1.Joi.object({
     createApiPageMD: utils_validation_1.Joi.function(),

package/lib/sidebars/index.js

@@ -23,11 +23,33 @@ function isInfoItem(item) {
 function isSchemaItem(item) {
     return item.type === "schema";
 }
+const createDocItem = (item, { sidebarOptions: { customProps }, basePath }) => {
+    var _a, _b;
+    const sidebar_label = item.frontMatter.sidebar_label;
+    const title = item.title;
+    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+    const className = item.type === "api"
+        ? (0, clsx_1.default)({
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+        }, item.api.method)
+        : (0, clsx_1.default)({
+            "menu__list-item--deprecated": item.schema.deprecated,
+        }, "schema");
+    return {
+        type: "doc",
+        id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+        label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
+        customProps: customProps,
+        className: className ? className : undefined,
+    };
+};
 function groupByTags(items, sidebarOptions, options, tags, docPath) {
+    var _a, _b;
     let { outputDir, label, showSchemas } = options;
     // Remove trailing slash before proceeding
     outputDir = outputDir.replace(/\/$/, "");
-    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
     const schemaItems = items.filter(isSchemaItem);
@@ -61,27 +83,11 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const basePath = docPath
         ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
         : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-    function createDocItem(item) {
-        var _a, _b;
-        const sidebar_label = item.frontMatter.sidebar_label;
-        const title = item.title;
-        const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
-        const className = item.type === "api"
-            ? (0, clsx_1.default)({
-                "menu__list-item--deprecated": item.api.deprecated,
-                "api-method": !!item.api.method,
-            }, item.api.method)
-            : (0, clsx_1.default)({
-                "menu__list-item--deprecated": item.schema.deprecated,
-            }, "schema");
-        return {
-            type: "doc",
-            id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
-            label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
-            customProps: customProps,
-            className: className ? className : undefined,
-        };
-    }
+    const createDocItemFnContext = {
+        sidebarOptions,
+        basePath,
+    };
+    const createDocItemFn = (_b = (_a = sidebarOptions.sidebarGenerators) === null || _a === void 0 ? void 0 : _a.createDocItem) !== null && _b !== void 0 ? _b : createDocItem;
     let rootIntroDoc = undefined;
     if (infoItems.length === 1) {
         const infoItem = infoItems[0];
@@ -139,14 +145,14 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
-            items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
+            items: [...taggedSchemaItems, ...taggedApiItems].map((item) => createDocItemFn(item, createDocItemFnContext)),
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
     // Handle items with no tag
     const untaggedItems = apiItems
         .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-        .map(createDocItem);
+        .map((item) => createDocItemFn(item, createDocItemFnContext));
     let untagged = [];
     if (untaggedItems.length > 0) {
         untagged = [
@@ -157,7 +163,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 collapsed: sidebarCollapsed,
                 items: apiItems
                     .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-                    .map(createDocItem),
+                    .map((item) => createDocItemFn(item, createDocItemFnContext)),
             },
         ];
     }
@@ -171,7 +177,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 collapsed: sidebarCollapsed,
                 items: schemaItems
                     .filter(({ schema }) => !schema["x-tags"])
-                    .map(createDocItem),
+                    .map((item) => createDocItemFn(item, createDocItemFnContext)),
             },
         ];
     }

package/lib/types.d.ts

@@ -1,3 +1,4 @@
+import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import type Request from "postman-collection";
 import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
@@ -34,6 +35,13 @@ export interface MarkdownGenerator {
     createTagPageMD?: (pageData: TagPageMetadata) => string;
     createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
+export type ApiDocItemGenerator = (item: ApiPageMetadata | SchemaPageMetadata, context: {
+    sidebarOptions: SidebarOptions;
+    basePath: string;
+}) => SidebarItemDoc;
+export interface SidebarGenerators {
+    createDocItem?: ApiDocItemGenerator;
+}
 export interface SidebarOptions {
     groupPathsBy?: string;
     categoryLinkSource?: "info" | "tag" | "auto";
@@ -42,6 +50,7 @@ export interface SidebarOptions {
     };
     sidebarCollapsible?: boolean;
     sidebarCollapsed?: boolean;
+    sidebarGenerators?: SidebarGenerators;
 }
 export interface APIVersionOptions {
     specPath: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-827",
+  "version": "0.0.0-833",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "759e2c14c7471bcc90a83071407fb0a8fd47ec35"
+  "gitHead": "88fa93f9d8676c5c4c2a210980373d615e829060"
 }

package/src/options.ts

@@ -7,12 +7,17 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
+const sidebarGenerators = Joi.object({
+  createDocItem: Joi.function(),
+});
+
 const sidebarOptions = Joi.object({
   groupPathsBy: Joi.string().valid("tag", "tagGroup"),
   categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
   sidebarCollapsed: Joi.boolean(),
+  sidebarGenerators: sidebarGenerators,
 });
 
 const markdownGenerators = Joi.object({

package/src/sidebars/index.ts

@@ -12,7 +12,6 @@ import {
   ProcessedSidebar,
   SidebarItemCategory,
   SidebarItemCategoryLinkConfig,
-  SidebarItemDoc,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import { posixPath } from "@docusaurus/utils";
 import clsx from "clsx";
@@ -27,6 +26,7 @@ import type {
   ApiMetadata,
   InfoPageMetadata,
   SchemaPageMetadata,
+  ApiDocItemGenerator,
 } from "../types";
 
 function isApiItem(item: ApiMetadata): item is ApiMetadata {
@@ -41,6 +41,37 @@ function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
   return item.type === "schema";
 }
 
+const createDocItem: ApiDocItemGenerator = (
+  item,
+  { sidebarOptions: { customProps }, basePath }
+) => {
+  const sidebar_label = item.frontMatter.sidebar_label;
+  const title = item.title;
+  const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+  const className =
+    item.type === "api"
+      ? clsx(
+          {
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+          },
+          item.api.method
+        )
+      : clsx(
+          {
+            "menu__list-item--deprecated": item.schema.deprecated,
+          },
+          "schema"
+        );
+  return {
+    type: "doc" as const,
+    id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+    label: (sidebar_label as string) ?? title ?? id,
+    customProps: customProps,
+    className: className ? className : undefined,
+  };
+};
+
 function groupByTags(
   items: ApiMetadata[],
   sidebarOptions: SidebarOptions,
@@ -53,12 +84,8 @@ function groupByTags(
   // Remove trailing slash before proceeding
   outputDir = outputDir.replace(/\/$/, "");
 
-  const {
-    sidebarCollapsed,
-    sidebarCollapsible,
-    customProps,
-    categoryLinkSource,
-  } = sidebarOptions;
+  const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } =
+    sidebarOptions;
 
   const apiItems = items.filter(isApiItem) as ApiPageMetadata[];
   const infoItems = items.filter(isInfoItem) as InfoPageMetadata[];
@@ -101,35 +128,13 @@ function groupByTags(
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-  function createDocItem(
-    item: ApiPageMetadata | SchemaPageMetadata
-  ): SidebarItemDoc {
-    const sidebar_label = item.frontMatter.sidebar_label;
-    const title = item.title;
-    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
-    const className =
-      item.type === "api"
-        ? clsx(
-            {
-              "menu__list-item--deprecated": item.api.deprecated,
-              "api-method": !!item.api.method,
-            },
-            item.api.method
-          )
-        : clsx(
-            {
-              "menu__list-item--deprecated": item.schema.deprecated,
-            },
-            "schema"
-          );
-    return {
-      type: "doc" as const,
-      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
-      label: (sidebar_label as string) ?? title ?? id,
-      customProps: customProps,
-      className: className ? className : undefined,
-    };
-  }
+
+  const createDocItemFnContext = {
+    sidebarOptions,
+    basePath,
+  };
+  const createDocItemFn =
+    sidebarOptions.sidebarGenerators?.createDocItem ?? createDocItem;
 
   let rootIntroDoc = undefined;
   if (infoItems.length === 1) {
@@ -208,7 +213,9 @@ function groupByTags(
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
-        items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
+        items: [...taggedSchemaItems, ...taggedApiItems].map((item) =>
+          createDocItemFn(item, createDocItemFnContext)
+        ),
       };
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -216,7 +223,7 @@ function groupByTags(
   // Handle items with no tag
   const untaggedItems = apiItems
     .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-    .map(createDocItem);
+    .map((item) => createDocItemFn(item, createDocItemFnContext));
   let untagged: SidebarItemCategory[] = [];
   if (untaggedItems.length > 0) {
     untagged = [
@@ -227,7 +234,7 @@ function groupByTags(
         collapsed: sidebarCollapsed!,
         items: apiItems
           .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-          .map(createDocItem),
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
       },
     ];
   }
@@ -242,7 +249,7 @@ function groupByTags(
         collapsed: sidebarCollapsed!,
         items: schemaItems
           .filter(({ schema }) => !schema["x-tags"])
-          .map(createDocItem),
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
       },
     ];
   }

package/src/types.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import type Request from "postman-collection";
 
 import {
@@ -57,12 +58,22 @@ export interface MarkdownGenerator {
   createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
 
+export type ApiDocItemGenerator = (
+  item: ApiPageMetadata | SchemaPageMetadata,
+  context: { sidebarOptions: SidebarOptions; basePath: string }
+) => SidebarItemDoc;
+
+export interface SidebarGenerators {
+  createDocItem?: ApiDocItemGenerator;
+}
+
 export interface SidebarOptions {
   groupPathsBy?: string;
   categoryLinkSource?: "info" | "tag" | "auto";
   customProps?: { [key: string]: unknown };
   sidebarCollapsible?: boolean;
   sidebarCollapsed?: boolean;
+  sidebarGenerators?: SidebarGenerators;
 }
 
 export interface APIVersionOptions {