docusaurus-plugin-openapi-docs 4.0.1 → 4.1.0

package/README.md

@@ -172,6 +172,8 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `markdownGenerators` | `object`  | `null`  | _Optional:_ Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
 | `showSchemas`        | `boolean` | `null`  | _Optional:_ If set to `true`, generates schema pages and adds them to the sidebar.                                                              |
 
+### sidebarOptions
+
 `sidebarOptions` can be configured with the following options:
 
 | Name                 | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -181,6 +183,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 +209,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/markdown/createCallbackMethodEndpoint.d.ts

@@ -0,0 +1 @@
+export declare function createCallbackMethodEndpoint(method: String, path: String): string[];

package/lib/markdown/createCallbackMethodEndpoint.js

@@ -0,0 +1,21 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCallbackMethodEndpoint = void 0;
+const utils_1 = require("./utils");
+function createCallbackMethodEndpoint(method, path) {
+    return [
+        (0, utils_1.create)("MethodEndpoint", {
+            method: method,
+            path: path,
+            context: "callback",
+        }),
+        "\n\n",
+    ];
+}
+exports.createCallbackMethodEndpoint = createCallbackMethodEndpoint;

package/lib/markdown/createCallbacks.js

@@ -7,8 +7,8 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCallbacks = void 0;
+const createCallbackMethodEndpoint_1 = require("./createCallbackMethodEndpoint");
 const createDescription_1 = require("./createDescription");
-const createMethodEndpoint_1 = require("./createMethodEndpoint");
 const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
 const createStatusCodes_1 = require("./createStatusCodes");
 const utils_1 = require("./utils");
@@ -54,7 +54,7 @@ function createCallbacks({ callbacks }) {
                                 label: `${method.toUpperCase()} ${name}`,
                                 value: `${method}-${name}`,
                                 children: [
-                                    (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
+                                    (0, createCallbackMethodEndpoint_1.createCallbackMethodEndpoint)(method, path),
                                     // TODO: add `deprecation notice` when markdown support is added
                                     (0, createDescription_1.createDescription)(description),
                                     (0, createRequestBodyDetails_1.createRequestBodyDetails)({

package/lib/markdown/createDeprecationNotice.js

@@ -12,11 +12,10 @@ function createAdmonition({ children }) {
     return `:::caution deprecated\n\n${(0, utils_1.render)(children)}\n\n:::`;
 }
 function createDeprecationNotice({ deprecated, description, }) {
-    return (0, utils_1.guard)(deprecated, () => {
-        var _a;
-        return createAdmonition({
-            children: (_a = (0, utils_1.clean)(description)) !== null && _a !== void 0 ? _a : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
-        });
-    });
+    return (0, utils_1.guard)(deprecated, () => createAdmonition({
+        children: description && description.length > 0
+            ? (0, utils_1.clean)(description)
+            : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
+    }));
 }
 exports.createDeprecationNotice = createDeprecationNotice;

package/lib/markdown/createMethodEndpoint.js

@@ -9,6 +9,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMethodEndpoint = void 0;
 const utils_1 = require("./utils");
 function createMethodEndpoint(method, path) {
-    return [(0, utils_1.create)("MethodEndpoint", { method: method, path: path }), "\n\n"];
+    return [
+        (0, utils_1.create)("MethodEndpoint", {
+            method: method,
+            path: path,
+            context: "endpoint",
+        }),
+        "\n\n",
+    ];
 }
 exports.createMethodEndpoint = createMethodEndpoint;

package/lib/markdown/createParamsDetails.js

@@ -35,10 +35,16 @@ function createParamsDetails({ parameters, type }) {
             (0, utils_1.create)("div", {
                 children: [
                     (0, utils_1.create)("ul", {
-                        children: params.map((param) => (0, utils_1.create)("ParamsItem", {
-                            className: "paramsItem",
-                            param: param,
-                        })),
+                        children: params.map((param) => {
+                            var _a, _b, _c, _d, _e;
+                            return (0, utils_1.create)("ParamsItem", {
+                                className: "paramsItem",
+                                param: {
+                                    ...param,
+                                    enumDescriptions: Object.entries((_e = (_b = (_a = param === null || param === void 0 ? void 0 : param.schema) === null || _a === void 0 ? void 0 : _a["x-enumDescriptions"]) !== null && _b !== void 0 ? _b : (_d = (_c = param === null || param === void 0 ? void 0 : param.schema) === null || _c === void 0 ? void 0 : _c.items) === null || _d === void 0 ? void 0 : _d["x-enumDescriptions"]) !== null && _e !== void 0 ? _e : {}),
+                                },
+                            });
+                        }),
                     }),
                 ],
             }),

package/lib/markdown/createSchema.js

@@ -90,6 +90,10 @@ function createAnyOneOf(schema) {
                         anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
                         delete anyOneSchema.allOf;
                     }
+                    if (anyOneSchema.oneOf !== undefined) {
+                        anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
+                        delete anyOneSchema.oneOf;
+                    }
                     if (anyOneSchema.items !== undefined) {
                         anyOneChildren.push(createItems(anyOneSchema));
                         delete anyOneSchema.items;
@@ -347,14 +351,14 @@ function createDetailsNode(name, schemaName, schema, required, nullable) {
                     (0, utils_1.create)("div", {
                         style: { marginLeft: "1rem" },
                         children: [
-                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
-                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                                children: (0, createDescription_1.createDescription)(message),
-                            })),
                             (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
                                 style: { marginTop: ".5rem", marginBottom: ".5rem" },
                                 children: (0, createDescription_1.createDescription)(description),
                             })),
+                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
+                                style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                children: (0, createDescription_1.createDescription)(message),
+                            })),
                             createNodes(schema, SCHEMA_TYPE),
                         ],
                     }),
@@ -474,17 +478,17 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
                         ]),
                     ],
                 }),
-                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
+                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
                     style: {
                         paddingLeft: "1rem",
                     },
-                    children: (0, createDescription_1.createDescription)(message),
+                    children: (0, createDescription_1.createDescription)(description),
                 })),
-                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
                     style: {
                         paddingLeft: "1rem",
                     },
-                    children: (0, createDescription_1.createDescription)(description),
+                    children: (0, createDescription_1.createDescription)(message),
                 })),
                 (0, utils_1.create)("DiscriminatorTabs", {
                     className: "openapi-tabs__discriminator",
@@ -539,38 +543,43 @@ function createEdges({ name, schema, required, discriminator, }) {
     }
     if (schema.allOf !== undefined) {
         const { mergedSchemas } = mergeAllOf(schema.allOf);
+        delete schema.allOf;
+        const combinedSchemas = { ...schema, ...mergedSchemas };
         if (SCHEMA_TYPE === "request") {
-            if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
+            if (combinedSchemas.readOnly && combinedSchemas.readOnly === true) {
                 return undefined;
             }
         }
         if (SCHEMA_TYPE === "response") {
-            if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+            if (combinedSchemas.writeOnly && combinedSchemas.writeOnly === true) {
                 return undefined;
             }
         }
-        const mergedSchemaName = (0, schema_1.getSchemaName)(mergedSchemas);
-        if (mergedSchemas.oneOf !== undefined ||
-            mergedSchemas.anyOf !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+        const mergedSchemaName = (0, schema_1.getSchemaName)(combinedSchemas);
+        if (name === "eventName") {
+            console.log(mergedSchemaName, combinedSchemas);
         }
-        if (mergedSchemas.properties !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+        if (combinedSchemas.oneOf !== undefined ||
+            combinedSchemas.anyOf !== undefined) {
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
+        }
+        if (combinedSchemas.properties !== undefined) {
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
         }
-        if (mergedSchemas.additionalProperties !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+        if (combinedSchemas.additionalProperties !== undefined) {
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
         }
         // array of objects
         if (((_d = mergedSchemas.items) === null || _d === void 0 ? void 0 : _d.properties) !== undefined) {
-            return createDetailsNode(name, mergedSchemaName, mergedSchemas, required, schema.nullable);
+            return createDetailsNode(name, mergedSchemaName, combinedSchemas, required, combinedSchemas.nullable);
         }
         return (0, utils_1.create)("SchemaItem", {
             collapsible: false,
             name,
             required: Array.isArray(required) ? required.includes(name) : required,
             schemaName: mergedSchemaName,
-            qualifierMessage: (0, schema_1.getQualifierMessage)(mergedSchemas),
-            schema: mergedSchemas,
+            qualifierMessage: (0, schema_1.getQualifierMessage)(combinedSchemas),
+            schema: combinedSchemas,
         });
     }
     // primitives and array of non-objects

package/lib/markdown/createSchema.test.js

@@ -218,6 +218,54 @@ describe("createNodes", () => {
             expect(await Promise.all((0, createSchema_1.createNodes)(schema, "response").map(async (md) => await prettier.format(md, { parser: "babel" })))).toMatchSnapshot();
         });
     });
+    describe("anyOf", () => {
+        it("should render primitives within anyOf", async () => {
+            const schema = {
+                type: "object",
+                properties: {
+                    oneOfProperty: {
+                        anyOf: [
+                            {
+                                type: "integer",
+                            },
+                            {
+                                type: "boolean",
+                            },
+                        ],
+                        title: "One of int or bool",
+                    },
+                },
+            };
+            expect(await Promise.all((0, createSchema_1.createNodes)(schema, "response").map(async (md) => await prettier.format(md, { parser: "babel" })))).toMatchSnapshot();
+        });
+        it("should render oneOf within anyOf", async () => {
+            const schema = {
+                type: "object",
+                properties: {
+                    oneOfProperty: {
+                        anyOf: [
+                            {
+                                oneOf: [
+                                    {
+                                        type: "integer",
+                                    },
+                                    {
+                                        type: "boolean",
+                                    },
+                                ],
+                                title: "An int or a bool",
+                            },
+                            {
+                                type: "string",
+                            },
+                        ],
+                        title: "One of int or bool, or a string",
+                    },
+                },
+            };
+            expect(await Promise.all((0, createSchema_1.createNodes)(schema, "response").map(async (md) => await prettier.format(md, { parser: "babel" })))).toMatchSnapshot();
+        });
+    });
     describe("allOf", () => {
         it("should render same-level properties with allOf", async () => {
             const schema = {

package/lib/markdown/utils.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
+ * It is designed for rendering HTML a strings.
+ */
 export type Children = string | undefined | (string | string[] | undefined)[];
 export type Props = Record<string, any> & {
     children?: Children;

package/lib/openapi/openapi.js

@@ -61,7 +61,7 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData, options, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7;
     // TODO: Find a better way to handle this
     let items = [];
     const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
@@ -212,15 +212,15 @@ function createItems(openapiData, options, sidebarOptions) {
         }
     }
     // Gather x-webhooks endpoints
-    for (let [path, pathObject] of Object.entries((_p = openapiData["x-webhooks"]) !== null && _p !== void 0 ? _p : {})) {
+    for (let [path, pathObject] of Object.entries((_q = (_p = openapiData["x-webhooks"]) !== null && _p !== void 0 ? _p : openapiData["webhooks"]) !== null && _q !== void 0 ? _q : {})) {
         path = "webhook";
         const { $ref, description, parameters, servers, summary, ...rest } = pathObject;
         for (let [method, operationObject] of Object.entries({ ...rest })) {
             method = "event";
-            const title = (_r = (_q = operationObject.summary) !== null && _q !== void 0 ? _q : operationObject.operationId) !== null && _r !== void 0 ? _r : "Missing summary";
+            const title = (_s = (_r = operationObject.summary) !== null && _r !== void 0 ? _r : operationObject.operationId) !== null && _s !== void 0 ? _s : "Missing summary";
             if (operationObject.description === undefined) {
                 operationObject.description =
-                    (_t = (_s = operationObject.summary) !== null && _s !== void 0 ? _s : operationObject.operationId) !== null && _t !== void 0 ? _t : "";
+                    (_u = (_t = operationObject.summary) !== null && _t !== void 0 ? _t : operationObject.operationId) !== null && _u !== void 0 ? _u : "";
             }
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
@@ -232,10 +232,10 @@ function createItems(openapiData, options, sidebarOptions) {
                     extensions.push({ key, value });
                 }
             }
-            const servers = (_v = (_u = operationObject.servers) !== null && _u !== void 0 ? _u : pathObject.servers) !== null && _v !== void 0 ? _v : openapiData.servers;
-            const security = (_w = operationObject.security) !== null && _w !== void 0 ? _w : openapiData.security;
+            const servers = (_w = (_v = operationObject.servers) !== null && _v !== void 0 ? _v : pathObject.servers) !== null && _w !== void 0 ? _w : openapiData.servers;
+            const security = (_x = operationObject.security) !== null && _x !== void 0 ? _x : openapiData.security;
             // Add security schemes so we know how to handle security.
-            const securitySchemes = (_x = openapiData.components) === null || _x === void 0 ? void 0 : _x.securitySchemes;
+            const securitySchemes = (_y = openapiData.components) === null || _y === void 0 ? void 0 : _y.securitySchemes;
             // Make sure schemes are lowercase. See: https://github.com/cloud-annotations/docusaurus-plugin-openapi/issues/79
             if (securitySchemes) {
                 for (let securityScheme of Object.values(securitySchemes)) {
@@ -245,7 +245,7 @@ function createItems(openapiData, options, sidebarOptions) {
                 }
             }
             let jsonRequestBodyExample;
-            const content = (_y = operationObject.requestBody) === null || _y === void 0 ? void 0 : _y.content;
+            const content = (_z = operationObject.requestBody) === null || _z === void 0 ? void 0 : _z.content;
             let body;
             for (let key in content) {
                 if (key.toLowerCase() === "application/json" ||
@@ -258,7 +258,7 @@ function createItems(openapiData, options, sidebarOptions) {
                 jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(body.schema);
             }
             // Handle vendor JSON media types
-            const bodyContent = (_z = operationObject.requestBody) === null || _z === void 0 ? void 0 : _z.content;
+            const bodyContent = (_0 = operationObject.requestBody) === null || _0 === void 0 ? void 0 : _0.content;
             if (bodyContent) {
                 const firstBodyContentKey = Object.keys(bodyContent)[0];
                 if (firstBodyContentKey.endsWith("+json")) {
@@ -325,13 +325,13 @@ function createItems(openapiData, options, sidebarOptions) {
         }
     }
     if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
-        Object.entries((_1 = (_0 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _0 === void 0 ? void 0 : _0.schemas) !== null && _1 !== void 0 ? _1 : {})
+        Object.entries((_2 = (_1 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _1 === void 0 ? void 0 : _1.schemas) !== null && _2 !== void 0 ? _2 : {})
             .flatMap(([_, s]) => s["x-tags"])
             .filter((item) => !!item).length > 0) {
         // Gather schemas
-        for (let [schema, schemaObject] of 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 : {})) {
+        for (let [schema, schemaObject] of Object.entries((_4 = (_3 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _3 === void 0 ? void 0 : _3.schemas) !== null && _4 !== void 0 ? _4 : {})) {
             if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true || schemaObject["x-tags"]) {
-                const baseIdSpaces = (_5 = (_4 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _4 === void 0 ? void 0 : _4.replace(" ", "-").toLowerCase()) !== null && _5 !== void 0 ? _5 : "";
+                const baseIdSpaces = (_6 = (_5 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _5 === void 0 ? void 0 : _5.replace(" ", "-").toLowerCase()) !== null && _6 !== void 0 ? _6 : "";
                 const baseId = (0, kebabCase_1.default)(baseIdSpaces);
                 const schemaDescription = schemaObject.description;
                 let splitDescription;
@@ -364,7 +364,7 @@ function createItems(openapiData, options, sidebarOptions) {
     }
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Get global tags
-        const tags = (_6 = openapiData.tags) !== null && _6 !== void 0 ? _6 : [];
+        const tags = (_7 = openapiData.tags) !== null && _7 !== void 0 ? _7 : [];
         // Get operation tags
         const apiItems = items.filter((item) => {
             return item.type === "api";

package/lib/openapi/types.d.ts

@@ -12,6 +12,7 @@ export interface OpenApiObject {
     tags?: TagObject[];
     externalDocs?: ExternalDocumentationObject;
     swagger?: string;
+    webhooks?: PathsObject;
     "x-webhooks"?: PathsObject;
     "x-tagGroups"?: TagGroupObject[];
 }
@@ -163,6 +164,7 @@ export interface ParameterObject {
     examples?: Map<ExampleObject>;
     content?: Map<MediaTypeObject>;
     param?: Object;
+    "x-enumDescriptions"?: Record<string, string>;
 }
 export interface ParameterObjectWithRef {
     name: string;
@@ -279,6 +281,7 @@ export type SchemaObject = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf"
     example?: any;
     deprecated?: boolean;
     "x-tags"?: string[];
+    "x-enumDescriptions"?: Record<string, string>;
 };
 export type SchemaObjectWithRef = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf" | "not" | "items" | "properties" | "additionalProperties"> & {
     type?: "string" | "number" | "integer" | "boolean" | "object" | "array";

package/lib/openapi/utils/services/OpenAPIParser.js

@@ -215,7 +215,7 @@ class OpenAPIParser {
         })
             .filter((child) => child !== undefined);
         for (const { $ref: subSchemaRef, schema: subSchema } of allOfSchemas) {
-            const { type, enum: enumProperty, properties, items, required, oneOf, anyOf, title, ...otherConstraints } = subSchema;
+            const { type, enum: enumProperty, "x-enumDescription": enumDescription, properties, items, required, oneOf, anyOf, title, ...otherConstraints } = subSchema;
             if (receiver.type !== type &&
                 receiver.type !== undefined &&
                 type !== undefined) {

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": "4.0.1",
+  "version": "4.1.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,7 +28,7 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/types": "^3.0.1",
+    "@docusaurus/types": "^3.5.0",
     "@types/fs-extra": "^9.0.13",
     "@types/json-pointer": "^1.0.31",
     "@types/json-schema": "^7.0.9",
@@ -38,9 +38,9 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@docusaurus/plugin-content-docs": "^3.0.1",
-    "@docusaurus/utils": "^3.0.1",
-    "@docusaurus/utils-validation": "^3.0.1",
+    "@docusaurus/plugin-content-docs": "^3.5.0",
+    "@docusaurus/utils": "^3.5.0",
+    "@docusaurus/utils-validation": "^3.5.0",
     "@redocly/openapi-core": "^1.10.5",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e228de93d24062c46fb206548dca7af9bc6264bb"
+  "gitHead": "4e771d309f6defe395449b26cc3c65814d72cbcc"
 }