docusaurus-plugin-openapi-docs 3.0.0-beta.5 → 3.0.0-beta.7

package/README.md

@@ -31,6 +31,7 @@ Key Features:
 
 | Docusaurus OpenAPI Docs | Docusaurus      |
 | ----------------------- | --------------- |
+| 3.0.0-beta.x (beta)     | `3.0.1 - 3.1.1` |
 | 2.0.x (current)         | `2.4.1 - 2.4.3` |
 | 1.7.3 (legacy)          | `2.0.1 - 2.2.0` |
 
@@ -159,6 +160,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | `baseUrl`            | `string`  | `null`  | _Optional:_ Version base URL used when generating version selector dropdown menu.                                                               |
 | `versions`           | `object`  | `null`  | _Optional:_ Set of options for versioning configuration. See below for a list of supported options.                                             |
 | `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` can be configured with the following options:
 

package/lib/index.js

@@ -78,7 +78,7 @@ function pluginOpenAPIDocs(context, options) {
     let docRouteBasePath = docData ? docData.routeBasePath : undefined;
     let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options, pluginId) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         let { specPath, outputDir, template, markdownGenerators, downloadUrl, sidebarOptions, } = options;
         // Remove trailing slash before proceeding
         outputDir = outputDir.replace(/\/$/, "");
@@ -93,7 +93,7 @@ function pluginOpenAPIDocs(context, options) {
             : path_1.default.resolve(siteDir, specPath);
         try {
             const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath);
-            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, options, sidebarOptions);
+            const [loadedApi, tags, tagGroups] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, options, sidebarOptions);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
@@ -105,7 +105,7 @@ function pluginOpenAPIDocs(context, options) {
             }
             // TODO: figure out better way to set default
             if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
-                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath);
+                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`;
                 sidebarSliceTemplate += `export default sidebar.apisidebar;\n`;
@@ -198,20 +198,35 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 <DocCardList items={useCurrentSidebarCategory().items}/>
 \`\`\`
       `;
+            const schemaMdTemplate = `---
+id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{frontMatter.description}}}"
+sidebar_label: "{{{title}}}"
+hide_title: true
+schema: true
+custom_edit_url: null
+---
+
+{{{markdown}}}
+            `;
             const apiPageGenerator = (_a = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createApiPageMD) !== null && _a !== void 0 ? _a : markdown_1.createApiPageMD;
             const infoPageGenerator = (_b = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createInfoPageMD) !== null && _b !== void 0 ? _b : markdown_1.createInfoPageMD;
             const tagPageGenerator = (_c = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createTagPageMD) !== null && _c !== void 0 ? _c : markdown_1.createTagPageMD;
+            const schemaPageGenerator = (_d = markdownGenerators === null || markdownGenerators === void 0 ? void 0 : markdownGenerators.createSchemaPageMD) !== null && _d !== void 0 ? _d : markdown_1.createSchemaPageMD;
+            const pageGeneratorByType = {
+                api: apiPageGenerator,
+                info: infoPageGenerator,
+                tag: tagPageGenerator,
+                schema: schemaPageGenerator,
+            };
             loadedApi.map(async (item) => {
                 if (item.type === "info") {
                     if (downloadUrl && isURL(downloadUrl)) {
                         item.downloadUrl = downloadUrl;
                     }
                 }
-                const markdown = item.type === "api"
-                    ? apiPageGenerator(item)
-                    : item.type === "info"
-                        ? infoPageGenerator(item)
-                        : tagPageGenerator(item);
+                const markdown = pageGeneratorByType[item.type](item);
                 item.markdown = markdown;
                 if (item.type === "api") {
                     // opportunity to compress JSON
@@ -277,6 +292,32 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                         }
                     }
                 }
+                if (item.type === "schema") {
+                    if (!fs_1.default.existsSync(`${outputDir}/schemas/${item.id}.schema.mdx`)) {
+                        if (!fs_1.default.existsSync(`${outputDir}/schemas`)) {
+                            try {
+                                fs_1.default.mkdirSync(`${outputDir}/schemas`, { recursive: true });
+                                console.log(chalk_1.default.green(`Successfully created "${outputDir}/schemas"`));
+                            }
+                            catch (err) {
+                                console.error(chalk_1.default.red(`Failed to create "${outputDir}/schemas"`), chalk_1.default.yellow(err));
+                            }
+                        }
+                        try {
+                            // kebabCase(arg) returns 0-length string when arg is undefined
+                            if (item.id.length === 0) {
+                                throw Error("Schema must have title defined");
+                            }
+                            // eslint-disable-next-line testing-library/render-result-naming-convention
+                            const schemaView = (0, mustache_1.render)(schemaMdTemplate, item);
+                            fs_1.default.writeFileSync(`${outputDir}/schemas/${item.id}.schema.mdx`, schemaView, "utf8");
+                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.schema.mdx"`));
+                        }
+                        catch (err) {
+                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/${item.id}.schema.mdx"`), chalk_1.default.yellow(err));
+                        }
+                    }
+                }
                 return;
             });
             return;
@@ -293,7 +334,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             cwd: path_1.default.resolve(apiDir),
             deep: 1,
         });
-        const sidebarFile = await (0, utils_1.Globby)(["sidebar.ts"], {
+        const schemaMdxFiles = await (0, utils_1.Globby)(["*.schema.mdx"], {
+            cwd: path_1.default.resolve(apiDir, "schemas"),
+            deep: 1,
+        });
+        const sidebarFile = await (0, utils_1.Globby)(["sidebar.js"], {
             cwd: path_1.default.resolve(apiDir),
             deep: 1,
         });
@@ -305,6 +350,14 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
             }
         }));
+        schemaMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/schemas/${mdx}`, (err) => {
+            if (err) {
+                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/schemas/${mdx}"`), chalk_1.default.yellow(err));
+            }
+            else {
+                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/schemas/${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));

package/lib/markdown/createAuthentication.js

@@ -148,11 +148,12 @@ function createAuthentication(securitySchemes) {
     };
     return (0, utils_1.create)("div", {
         children: [
-            (0, utils_1.create)("h2", {
+            (0, utils_1.create)("Heading", {
                 children: "Authentication",
                 id: "authentication",
-                style: { marginBottom: "1rem" },
-            }),
+                as: "h2",
+                className: "openapi-tabs__heading",
+            }, { inline: true }),
             (0, utils_1.create)("SchemaTabs", {
                 className: "openapi-tabs__security-schemes",
                 children: Object.entries(securitySchemes).map(([schemeKey, schemeObj]) => (0, utils_1.create)("TabItem", {

package/lib/markdown/createCallbacks.js

@@ -25,10 +25,12 @@ function createCallbacks({ callbacks }) {
             (0, utils_1.create)("div", {
                 className: "openapi__divider",
             }),
-            (0, utils_1.create)("h2", {
+            (0, utils_1.create)("Heading", {
                 children: "Callbacks",
                 id: "callbacks",
-            }),
+                as: "h2",
+                className: "openapi-tabs__heading",
+            }, { inline: true }),
             (0, utils_1.create)("OperationTabs", {
                 className: "openapi-tabs__operation",
                 children: callbacksNames.flatMap((name) => {

package/lib/markdown/createHeading.js

@@ -10,10 +10,11 @@ exports.createHeading = void 0;
 const utils_1 = require("./utils");
 function createHeading(heading) {
     return [
-        (0, utils_1.create)("h1", {
-            className: "openapi__heading",
+        (0, utils_1.create)("Heading", {
             children: (0, utils_1.clean)(heading),
-        }),
+            as: "h1",
+            className: "openapi__heading",
+        }, { inline: true }),
         `\n\n`,
     ];
 }

package/lib/markdown/createRequestHeader.d.ts

@@ -1 +1 @@
-export declare function createRequestHeader(header: string): string;
+export declare function createRequestHeader(header: string): string[];

package/lib/markdown/createRequestHeader.js

@@ -7,7 +7,16 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRequestHeader = void 0;
+const utils_1 = require("./utils");
 function createRequestHeader(header) {
-    return `## ${header}\n\n`;
+    return [
+        (0, utils_1.create)("Heading", {
+            children: header,
+            id: header.replace(" ", "-").toLowerCase(),
+            as: "h2",
+            className: "openapi-tabs__heading",
+        }, { inline: true }),
+        `\n\n`,
+    ];
 }
 exports.createRequestHeader = createRequestHeader;

package/lib/markdown/index.d.ts

@@ -1,4 +1,5 @@
-import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
+import { ApiPageMetadata, InfoPageMetadata, SchemaPageMetadata, TagPageMetadata } from "../types";
 export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, callbacks, }, infoPath, frontMatter, }: ApiPageMetadata): string;
 export declare function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }: InfoPageMetadata): string;
 export declare function createTagPageMD({ tag: { description } }: TagPageMetadata): string;
+export declare function createSchemaPageMD({ schema }: SchemaPageMetadata): string;

package/lib/markdown/index.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTagPageMD = exports.createInfoPageMD = exports.createApiPageMD = void 0;
+exports.createSchemaPageMD = exports.createTagPageMD = exports.createInfoPageMD = exports.createApiPageMD = void 0;
 const createAuthentication_1 = require("./createAuthentication");
 const createAuthorization_1 = require("./createAuthorization");
 const createCallbacks_1 = require("./createCallbacks");
@@ -21,6 +21,7 @@ const createMethodEndpoint_1 = require("./createMethodEndpoint");
 const createParamsDetails_1 = require("./createParamsDetails");
 const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
 const createRequestHeader_1 = require("./createRequestHeader");
+const createSchema_1 = require("./createSchema");
 const createStatusCodes_1 = require("./createStatusCodes");
 const createTermsOfService_1 = require("./createTermsOfService");
 const createVendorExtensions_1 = require("./createVendorExtensions");
@@ -38,6 +39,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import Markdown from "@theme/Markdown";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import OperationTabs from "@theme/OperationTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         (0, createHeading_1.createHeading)(title),
@@ -48,7 +50,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
             : undefined,
         (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),
         (0, createDescription_1.createDescription)(description),
-        (0, createRequestHeader_1.createRequestHeader)("Request"),
+        requestBody || parameters ? (0, createRequestHeader_1.createRequestHeader)("Request") : undefined,
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "path" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "query" }),
         (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "header" }),
@@ -65,6 +67,7 @@ exports.createApiPageMD = createApiPageMD;
 function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }) {
     return (0, utils_1.render)([
         `import ApiLogo from "@theme/ApiLogo";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import TabItem from "@theme/TabItem";\n`,
         `import Export from "@theme/ApiExplorer/Export";\n\n`,
@@ -84,3 +87,19 @@ function createTagPageMD({ tag: { description } }) {
     return (0, utils_1.render)([(0, createDescription_1.createDescription)(description)]);
 }
 exports.createTagPageMD = createTagPageMD;
+function createSchemaPageMD({ schema }) {
+    const { title = "", description } = schema;
+    return (0, utils_1.render)([
+        `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
+        `import SchemaItem from "@theme/SchemaItem";\n`,
+        `import SchemaTabs from "@theme/SchemaTabs";\n`,
+        `import Heading from "@theme/Heading";\n`,
+        `import TabItem from "@theme/TabItem";\n\n`,
+        (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
+        (0, createDescription_1.createDescription)(description),
+        (0, utils_1.create)("ul", {
+            children: (0, createSchema_1.createNodes)(schema, "response"),
+        }),
+    ]);
+}
+exports.createSchemaPageMD = createSchemaPageMD;

package/lib/markdown/utils.d.ts

@@ -2,7 +2,10 @@ export type Children = string | undefined | (string | string[] | undefined)[];
 export type Props = Record<string, any> & {
     children?: Children;
 };
-export declare function create(tag: string, props: Props): string;
+export type Options = {
+    inline?: boolean;
+};
+export declare function create(tag: string, props: Props, options?: Options): string;
 export declare function guard<T>(value: T | undefined, cb: (value: T) => Children): string;
 export declare function render(children: Children): string;
 export declare const lessThan: RegExp;

package/lib/markdown/utils.js

@@ -7,20 +7,24 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clean = exports.codeBlock = exports.curlyBrackets = exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
-function create(tag, props) {
+function create(tag, props, options = {}) {
     const { children, ...rest } = props;
     let propString = "";
     for (const [key, value] of Object.entries(rest)) {
         propString += `\n  ${key}={${JSON.stringify(value)}}`;
     }
-    propString += propString ? "\n" : "";
     let indentedChildren = render(children).replace(/^/gm, "  ");
+    if (options.inline) {
+        propString += `\n  children={${JSON.stringify(children)}}`;
+        indentedChildren = "";
+    }
+    propString += propString ? "\n" : "";
     indentedChildren += indentedChildren ? "\n" : "";
     return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
 exports.create = create;
 function guard(value, cb) {
-    if (!!value) {
+    if (!!value || value === 0) {
         const children = cb(value);
         return render(children);
     }

package/lib/openapi/openapi.d.ts

@@ -1,4 +1,4 @@
-import { OpenApiObject, TagObject } from "./types";
+import { OpenApiObject, TagGroupObject, TagObject } from "./types";
 import { ApiMetadata, APIOptions, SidebarOptions } from "../types";
 interface OpenApiFiles {
     source: string;
@@ -6,7 +6,7 @@ interface OpenApiFiles {
     data: OpenApiObject;
 }
 export declare function readOpenapiFiles(openapiPath: string): Promise<OpenApiFiles[]>;
-export declare function processOpenapiFiles(files: OpenApiFiles[], options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][]]>;
-export declare function processOpenapiFile(openapiData: OpenApiObject, options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
+export declare function processOpenapiFiles(files: OpenApiFiles[], options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][], TagGroupObject[]]>;
+export declare function processOpenapiFile(openapiData: OpenApiObject, options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[], TagGroupObject[]]>;
 export declare function getTagDisplayName(tagName: string, tags: TagObject[]): string;
 export {};

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;
+    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;
     // TODO: Find a better way to handle this
     let items = [];
     const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
@@ -324,9 +324,42 @@ function createItems(openapiData, options, sidebarOptions) {
             items.push(apiPage);
         }
     }
+    if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true) {
+        // Gather schemas
+        for (let [schema, schemaObject] of 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 : {})) {
+            const baseIdSpaces = (_3 = (_2 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _2 === void 0 ? void 0 : _2.replace(" ", "-").toLowerCase()) !== null && _3 !== void 0 ? _3 : "";
+            const baseId = (0, kebabCase_1.default)(baseIdSpaces);
+            const schemaDescription = schemaObject.description;
+            let splitDescription;
+            if (schemaDescription) {
+                splitDescription = schemaDescription.match(/[^\r\n]+/g);
+            }
+            const schemaPage = {
+                type: "schema",
+                id: baseId,
+                infoId: infoId !== null && infoId !== void 0 ? infoId : "",
+                unversionedId: baseId,
+                title: schemaObject.title
+                    ? schemaObject.title.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                    : schema,
+                description: schemaObject.description
+                    ? schemaObject.description.replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                    : "",
+                frontMatter: {
+                    description: splitDescription
+                        ? splitDescription[0]
+                            .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
+                            .replace(/\s+$/, "")
+                        : "",
+                },
+                schema: schemaObject,
+            };
+            items.push(schemaPage);
+        }
+    }
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Get global tags
-        const tags = (_0 = openapiData.tags) !== null && _0 !== void 0 ? _0 : [];
+        const tags = (_4 = openapiData.tags) !== null && _4 !== void 0 ? _4 : [];
         // Get operation tags
         const apiItems = items.filter((item) => {
             return item.type === "api";
@@ -375,7 +408,9 @@ function bindCollectionToApiItems(items, postmanCollection) {
             .getPath({ unresolved: true }) // unresolved returns "/:variableName" instead of "/<type>"
             .replace(/(?<![a-z0-9-_]+):([a-z0-9-_]+)/gi, "{$1}"); // replace "/:variableName" with "/{variableName}"
         const apiItem = items.find((item) => {
-            if (item.type === "info" || item.type === "tag") {
+            if (item.type === "info" ||
+                item.type === "tag" ||
+                item.type === "schema") {
                 return false;
             }
             return item.api.path === path && item.api.method === method;
@@ -426,7 +461,8 @@ async function processOpenapiFiles(files, options, sidebarOptions) {
                 ...item,
             }));
             const tags = processedFile[1];
-            return [itemsObjectsArray, tags];
+            const tagGroups = processedFile[2];
+            return [itemsObjectsArray, tags, tagGroups];
         }
         console.warn(chalk_1.default.yellow(`WARNING: the following OpenAPI spec returned undefined: ${file.source}`));
         return [];
@@ -449,7 +485,20 @@ async function processOpenapiFiles(files, options, sidebarOptions) {
         // Remove undefined tags due to transient parsing errors
         return x !== undefined;
     });
-    return [items, tags];
+    const tagGroups = metadata
+        .map(function (x) {
+        return x[2];
+    })
+        .flat()
+        .filter(function (x) {
+        // Remove undefined tags due to transient parsing errors
+        return x !== undefined;
+    });
+    return [
+        items,
+        tags,
+        tagGroups,
+    ];
 }
 exports.processOpenapiFiles = processOpenapiFiles;
 async function processOpenapiFile(openapiData, options, sidebarOptions) {
@@ -460,7 +509,11 @@ async function processOpenapiFile(openapiData, options, sidebarOptions) {
     if (openapiData.tags !== undefined) {
         tags = openapiData.tags;
     }
-    return [items, tags];
+    let tagGroups = [];
+    if (openapiData["x-tagGroups"] !== undefined) {
+        tagGroups = openapiData["x-tagGroups"];
+    }
+    return [items, tags, tagGroups];
 }
 exports.processOpenapiFile = processOpenapiFile;
 // order for picking items as a display name of tags

package/lib/openapi/openapi.test.js

@@ -24,6 +24,8 @@ describe("openapi", () => {
             const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
             expect(yaml).toBeTruthy();
             expect(yaml === null || yaml === void 0 ? void 0 : yaml.sourceDirName).toBe(".");
+            expect(yaml === null || yaml === void 0 ? void 0 : yaml.data.tags).toBeDefined();
+            expect(yaml === null || yaml === void 0 ? void 0 : yaml.data["x-tagGroups"]).toBeDefined();
         });
     });
 });

package/lib/openapi/types.d.ts

@@ -13,6 +13,7 @@ export interface OpenApiObject {
     externalDocs?: ExternalDocumentationObject;
     swagger?: string;
     "x-webhooks"?: PathsObject;
+    "x-tagGroups"?: TagGroupObject[];
 }
 export interface OpenApiObjectWithRef {
     openapi: string;
@@ -252,6 +253,10 @@ export interface TagObject {
     externalDocs?: ExternalDocumentationObject;
     "x-displayName"?: string;
 }
+export interface TagGroupObject {
+    name: string;
+    tags: string[];
+}
 export interface ReferenceObject {
     $ref: string;
 }

package/lib/options.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const sidebarOptions = utils_validation_1.Joi.object({
-    groupPathsBy: utils_validation_1.Joi.string().valid("tag"),
+    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(),
@@ -34,6 +34,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         showExtensions: utils_validation_1.Joi.boolean(),
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
+        showSchemas: utils_validation_1.Joi.boolean(),
         version: utils_validation_1.Joi.string().when("versions", {
             is: utils_validation_1.Joi.exist(),
             then: utils_validation_1.Joi.required(),

package/lib/sidebars/index.d.ts

@@ -1,4 +1,4 @@
 import { ProcessedSidebar } from "@docusaurus/plugin-content-docs/src/sidebars/types";
-import { TagObject } from "../openapi/types";
+import { TagGroupObject, TagObject } from "../openapi/types";
 import type { SidebarOptions, APIOptions, ApiMetadata } from "../types";
-export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[][], docPath: string): ProcessedSidebar;
+export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[][], docPath: string, tagGroups?: TagGroupObject[]): ProcessedSidebar;

package/lib/sidebars/index.js

@@ -20,6 +20,9 @@ function isApiItem(item) {
 function isInfoItem(item) {
     return item.type === "info";
 }
+function isSchemaItem(item) {
+    return item.type === "schema";
+}
 function groupByTags(items, sidebarOptions, options, tags, docPath) {
     let { outputDir, label } = options;
     // Remove trailing slash before proceeding
@@ -27,6 +30,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
+    const schemaItems = items.filter(isSchemaItem);
     const intros = infoItems.map((item) => {
         return {
             id: item.id,
@@ -48,7 +52,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             apiTags.push(tag.name);
         }
     });
-    apiTags = (0, uniq_1.default)(apiTags.concat(operationTags));
+    // apiTags = uniq(apiTags.concat(operationTags));
     const basePath = docPath
         ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
         : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
@@ -56,16 +60,21 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
         var _a, _b;
         const sidebar_label = item.frontMatter.sidebar_label;
         const title = item.title;
-        const id = item.id;
+        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,
+            });
         return {
             type: "doc",
-            id: basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
+            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: (0, clsx_1.default)({
-                "menu__list-item--deprecated": item.api.deprecated,
-                "api-method": !!item.api.method,
-            }, item.api.method),
+            className: className ? className : undefined,
         };
     }
     let rootIntroDoc = undefined;
@@ -147,16 +156,47 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             },
         ];
     }
+    let schemas = [];
+    if (schemaItems.length > 0) {
+        schemas = [
+            {
+                type: "category",
+                label: "Schemas",
+                collapsible: sidebarCollapsible,
+                collapsed: sidebarCollapsed,
+                items: schemaItems.map(createDocItem),
+            },
+        ];
+    }
     // Shift root intro doc to top of sidebar
     // TODO: Add input validation for categoryLinkSource options
     if (rootIntroDoc && categoryLinkSource !== "info") {
         tagged.unshift(rootIntroDoc);
     }
-    return [...tagged, ...untagged];
+    return [...tagged, ...untagged, ...schemas];
 }
-function generateSidebarSlice(sidebarOptions, options, api, tags, docPath) {
+function generateSidebarSlice(sidebarOptions, options, api, tags, docPath, tagGroups) {
     let sidebarSlice = [];
-    if (sidebarOptions.groupPathsBy === "tag") {
+    if (sidebarOptions.groupPathsBy === "tagGroup") {
+        tagGroups === null || tagGroups === void 0 ? void 0 : tagGroups.forEach((tagGroup) => {
+            //filter tags only included in group
+            const filteredTags = [];
+            tags[0].forEach((tag) => {
+                if (tagGroup.tags.includes(tag.name)) {
+                    filteredTags.push(tag);
+                }
+            });
+            const groupCategory = {
+                type: "category",
+                label: tagGroup.name,
+                collapsible: true,
+                collapsed: true,
+                items: groupByTags(api, sidebarOptions, options, [filteredTags], docPath),
+            };
+            sidebarSlice.push(groupCategory);
+        });
+    }
+    else if (sidebarOptions.groupPathsBy === "tag") {
         sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
     }
     return sidebarSlice;