docusaurus-plugin-openapi-docs 0.0.0-698 → 0.0.0-700

package/README.md

@@ -159,6 +159,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

@@ -77,7 +77,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(/\/$/, "");
@@ -92,7 +92,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 });
@@ -104,7 +104,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);
                 const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
                 const view = (0, mustache_1.render)(sidebarSliceTemplate, {
                     slice: JSON.stringify(sidebarSlice),
@@ -195,20 +195,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
@@ -274,6 +289,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;
@@ -290,6 +331,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             cwd: path_1.default.resolve(apiDir),
             deep: 1,
         });
+        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,
@@ -302,6 +347,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/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");
@@ -84,3 +85,18 @@ 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 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/openapi/openapi.d.ts

@@ -1,12 +1,12 @@
 import { ApiMetadata, APIOptions, SidebarOptions } from "../types";
-import { OpenApiObject, TagObject } from "./types";
+import { OpenApiObject, TagGroupObject, TagObject } from "./types";
 interface OpenApiFiles {
     source: string;
     sourceDirName: string;
     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;

package/lib/types.d.ts

@@ -1,5 +1,5 @@
 import type Request from "@paloaltonetworks/postman-collection";
-import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./openapi/types";
+import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
@@ -24,11 +24,13 @@ export interface APIOptions {
     };
     proxy?: string;
     markdownGenerators?: MarkdownGenerator;
+    showSchemas?: boolean;
 }
 export interface MarkdownGenerator {
     createApiPageMD?: (pageData: ApiPageMetadata) => string;
     createInfoPageMD?: (pageData: InfoPageMetadata) => string;
     createTagPageMD?: (pageData: TagPageMetadata) => string;
+    createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
 export interface SidebarOptions {
     groupPathsBy?: string;
@@ -48,7 +50,7 @@ export interface APIVersionOptions {
 export interface LoadedContent {
     loadedApi: ApiMetadata[];
 }
-export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
+export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata | SchemaPageMetadata;
 export interface ApiMetadataBase {
     sidebar?: string;
     previous?: ApiNavLink;
@@ -100,6 +102,17 @@ export interface TagPageMetadata extends ApiMetadataBase {
     tag: TagObject;
     markdown?: string;
 }
+export interface SchemaPageMetadata extends ApiMetadataBase {
+    type: "schema";
+    schema: SchemaObject;
+    markdown?: string;
+}
+export interface TagGroupPageMetadata extends ApiMetadataBase {
+    type: "tagGroup";
+    name: string;
+    tags: TagObject[];
+    markdown?: string;
+}
 export declare type ApiInfo = InfoObject;
 export interface ApiNavLink {
     title: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-698",
+  "version": "0.0.0-700",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "4fd97549c952b6b527c1485255d9c2f75b838853"
+  "gitHead": "309ea5d0c101d526975380a13915decebca3e86b"
 }

package/src/index.ts

@@ -14,11 +14,25 @@ import { Globby, posixPath } from "@docusaurus/utils";
 import chalk from "chalk";
 import { render } from "mustache";
 
-import { createApiPageMD, createInfoPageMD, createTagPageMD } from "./markdown";
+import {
+  createApiPageMD,
+  createInfoPageMD,
+  createSchemaPageMD,
+  createTagPageMD,
+} from "./markdown";
 import { readOpenapiFiles, processOpenapiFiles } from "./openapi";
 import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
-import type { PluginOptions, LoadedContent, APIOptions } from "./types";
+import type {
+  PluginOptions,
+  LoadedContent,
+  APIOptions,
+  ApiMetadata,
+  ApiPageMetadata,
+  InfoPageMetadata,
+  TagPageMetadata,
+  SchemaPageMetadata,
+} from "./types";
 
 export function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
@@ -117,7 +131,7 @@ export default function pluginOpenAPIDocs(
 
     try {
       const openapiFiles = await readOpenapiFiles(contentPath);
-      const [loadedApi, tags] = await processOpenapiFiles(
+      const [loadedApi, tags, tagGroups] = await processOpenapiFiles(
         openapiFiles,
         options,
         sidebarOptions!
@@ -141,7 +155,8 @@ export default function pluginOpenAPIDocs(
           options,
           loadedApi,
           tags,
-          docPath
+          docPath,
+          tagGroups
         );
 
         const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
@@ -244,12 +259,43 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 \`\`\`
       `;
 
+      const schemaMdTemplate = `---
+id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{frontMatter.description}}}"
+sidebar_label: "{{{title}}}"
+hide_title: true
+schema: true
+custom_edit_url: null
+---
+
+{{{markdown}}}
+            `;
+
       const apiPageGenerator =
         markdownGenerators?.createApiPageMD ?? createApiPageMD;
       const infoPageGenerator =
         markdownGenerators?.createInfoPageMD ?? createInfoPageMD;
       const tagPageGenerator =
         markdownGenerators?.createTagPageMD ?? createTagPageMD;
+      const schemaPageGenerator =
+        markdownGenerators?.createSchemaPageMD ?? createSchemaPageMD;
+
+      const pageGeneratorByType: {
+        [key in ApiMetadata["type"]]: (
+          pageData: {
+            api: ApiPageMetadata;
+            info: InfoPageMetadata;
+            tag: TagPageMetadata;
+            schema: SchemaPageMetadata;
+          }[key]
+        ) => string;
+      } = {
+        api: apiPageGenerator,
+        info: infoPageGenerator,
+        tag: tagPageGenerator,
+        schema: schemaPageGenerator,
+      };
 
       loadedApi.map(async (item) => {
         if (item.type === "info") {
@@ -257,12 +303,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             item.downloadUrl = downloadUrl;
           }
         }
-        const markdown =
-          item.type === "api"
-            ? apiPageGenerator(item)
-            : item.type === "info"
-            ? infoPageGenerator(item)
-            : tagPageGenerator(item);
+        const markdown = pageGeneratorByType[item.type](item as any);
         item.markdown = markdown;
         if (item.type === "api") {
           // opportunity to compress JSON
@@ -363,6 +404,49 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
             }
           }
         }
+
+        if (item.type === "schema") {
+          if (!fs.existsSync(`${outputDir}/schemas/${item.id}.schema.mdx`)) {
+            if (!fs.existsSync(`${outputDir}/schemas`)) {
+              try {
+                fs.mkdirSync(`${outputDir}/schemas`, { recursive: true });
+                console.log(
+                  chalk.green(`Successfully created "${outputDir}/schemas"`)
+                );
+              } catch (err) {
+                console.error(
+                  chalk.red(`Failed to create "${outputDir}/schemas"`),
+                  chalk.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 = render(schemaMdTemplate, item);
+              fs.writeFileSync(
+                `${outputDir}/schemas/${item.id}.schema.mdx`,
+                schemaView,
+                "utf8"
+              );
+              console.log(
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.schema.mdx"`
+                )
+              );
+            } catch (err) {
+              console.error(
+                chalk.red(
+                  `Failed to write "${outputDir}/${item.id}.schema.mdx"`
+                ),
+                chalk.yellow(err)
+              );
+            }
+          }
+        }
         return;
       });
 
@@ -380,6 +464,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
       cwd: path.resolve(apiDir),
       deep: 1,
     });
+    const schemaMdxFiles = await Globby(["*.schema.mdx"], {
+      cwd: path.resolve(apiDir, "schemas"),
+      deep: 1,
+    });
     const sidebarFile = await Globby(["sidebar.js"], {
       cwd: path.resolve(apiDir),
       deep: 1,
@@ -397,6 +485,21 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
       })
     );
 
+    schemaMdxFiles.map((mdx) =>
+      fs.unlink(`${apiDir}/schemas/${mdx}`, (err) => {
+        if (err) {
+          console.error(
+            chalk.red(`Cleanup failed for "${apiDir}/schemas/${mdx}"`),
+            chalk.yellow(err)
+          );
+        } else {
+          console.log(
+            chalk.green(`Cleanup succeeded for "${apiDir}/schemas/${mdx}"`)
+          );
+        }
+      })
+    );
+
     sidebarFile.map((sidebar) =>
       fs.unlink(`${apiDir}/${sidebar}`, (err) => {
         if (err) {

package/src/markdown/index.ts

@@ -11,7 +11,12 @@ import {
   MediaTypeObject,
   SecuritySchemeObject,
 } from "../openapi/types";
-import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
+import {
+  ApiPageMetadata,
+  InfoPageMetadata,
+  SchemaPageMetadata,
+  TagPageMetadata,
+} from "../types";
 import { createAuthentication } from "./createAuthentication";
 import { createAuthorization } from "./createAuthorization";
 import { createCallbacks } from "./createCallbacks";
@@ -26,11 +31,12 @@ import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createRequestHeader } from "./createRequestHeader";
+import { createNodes } from "./createSchema";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
 import { createVendorExtensions } from "./createVendorExtensions";
 import { createVersionBadge } from "./createVersionBadge";
-import { greaterThan, lessThan, render } from "./utils";
+import { create, greaterThan, lessThan, render } from "./utils";
 
 interface RequestBodyProps {
   title: string;
@@ -130,3 +136,18 @@ export function createInfoPageMD({
 export function createTagPageMD({ tag: { description } }: TagPageMetadata) {
   return render([createDescription(description)]);
 }
+
+export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
+  const { title = "", description } = schema;
+  return render([
+    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
+    `import SchemaItem from "@theme/SchemaItem";\n`,
+    `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import TabItem from "@theme/TabItem";\n\n`,
+    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createDescription(description),
+    create("ul", {
+      children: createNodes(schema, "response"),
+    }),
+  ]);
+}

package/src/openapi/__fixtures__/examples/openapi.yaml

@@ -11,3 +11,32 @@ paths:
       responses:
         200:
           description: OK
+
+tags:
+  - name: tag1
+    description: Everything about your Pets
+    x-displayName: Tag 1
+  - name: tag2
+    description: Tag 2 description
+    x-displayName: Tag 2
+  - name: tag3
+    description: Tag 3 description
+    x-displayName: Tag 3
+  - name: tag4
+    description: Tag 4 description
+    x-displayName: Tag 4
+
+x-tagGroups:
+  - name: Tag 1 & 2
+    tags:
+      - tag1
+      - tag2
+  - name: Trinity
+    tags:
+      - tag1
+      - tag2
+      - tag3
+  - name: Last Two
+    tags:
+      - tag3
+      - tag4

package/src/openapi/openapi.test.ts

@@ -28,6 +28,9 @@ describe("openapi", () => {
       const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
       expect(yaml).toBeTruthy();
       expect(yaml?.sourceDirName).toBe(".");
+
+      expect(yaml?.data.tags).toBeDefined();
+      expect(yaml?.data["x-tagGroups"]).toBeDefined();
     });
   });
 });

package/src/openapi/openapi.ts

@@ -24,11 +24,12 @@ import {
   APIOptions,
   ApiPageMetadata,
   InfoPageMetadata,
+  SchemaPageMetadata,
   SidebarOptions,
   TagPageMetadata,
 } from "../types";
 import { sampleRequestFromSchema } from "./createRequestExample";
-import { OpenApiObject, TagObject } from "./types";
+import { OpenApiObject, TagGroupObject, TagObject } from "./types";
 import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
@@ -409,6 +410,46 @@ function createItems(
     }
   }
 
+  if (options?.showSchemas === true) {
+    // Gather schemas
+    for (let [schema, schemaObject] of Object.entries(
+      openapiData?.components?.schemas ?? {}
+    )) {
+      const baseIdSpaces =
+        schemaObject?.title?.replace(" ", "-").toLowerCase() ?? "";
+      const baseId = kebabCase(baseIdSpaces);
+
+      const schemaDescription = schemaObject.description;
+      let splitDescription: any;
+      if (schemaDescription) {
+        splitDescription = schemaDescription.match(/[^\r\n]+/g);
+      }
+
+      const schemaPage: PartialPage<SchemaPageMetadata> = {
+        type: "schema",
+        id: baseId,
+        infoId: 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?.categoryLinkSource === "tag") {
     // Get global tags
     const tags: TagObject[] = openapiData.tags ?? [];
@@ -471,7 +512,11 @@ function bindCollectionToApiItems(
       .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;
@@ -534,7 +579,7 @@ export async function processOpenapiFiles(
   files: OpenApiFiles[],
   options: APIOptions,
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[][]]> {
+): Promise<[ApiMetadata[], TagObject[][], TagGroupObject[]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
       const processedFile = await processOpenapiFile(
@@ -546,7 +591,8 @@ export async function processOpenapiFiles(
         ...item,
       }));
       const tags = processedFile[1];
-      return [itemsObjectsArray, tags];
+      const tagGroups = processedFile[2];
+      return [itemsObjectsArray, tags, tagGroups];
     }
     console.warn(
       chalk.yellow(
@@ -565,6 +611,7 @@ export async function processOpenapiFiles(
       // Remove undefined items due to transient parsing errors
       return x !== undefined;
     });
+
   const tags = metadata
     .map(function (x) {
       return x[1];
@@ -573,14 +620,29 @@ export async function processOpenapiFiles(
       // Remove undefined tags due to transient parsing errors
       return x !== undefined;
     });
-  return [items as ApiMetadata[], tags as TagObject[][]];
+
+  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 as ApiMetadata[],
+    tags as TagObject[][],
+    tagGroups as TagGroupObject[],
+  ];
 }
 
 export async function processOpenapiFile(
   openapiData: OpenApiObject,
   options: APIOptions,
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[]]> {
+): Promise<[ApiMetadata[], TagObject[], TagGroupObject[]]> {
   const postmanCollection = await createPostmanCollection(openapiData);
   const items = createItems(openapiData, options, sidebarOptions);
 
@@ -590,7 +652,13 @@ export async function processOpenapiFile(
   if (openapiData.tags !== undefined) {
     tags = openapiData.tags;
   }
-  return [items, tags];
+
+  let tagGroups: TagGroupObject[] = [];
+  if (openapiData["x-tagGroups"] !== undefined) {
+    tagGroups = openapiData["x-tagGroups"];
+  }
+
+  return [items, tags, tagGroups];
 }
 
 // order for picking items as a display name of tags

package/src/openapi/types.ts

@@ -22,6 +22,7 @@ export interface OpenApiObject {
   externalDocs?: ExternalDocumentationObject;
   swagger?: string;
   "x-webhooks"?: PathsObject;
+  "x-tagGroups"?: TagGroupObject[];
 }
 
 export interface OpenApiObjectWithRef {
@@ -311,6 +312,11 @@ export interface TagObject {
   "x-displayName"?: string;
 }
 
+export interface TagGroupObject {
+  name: string;
+  tags: string[];
+}
+
 export interface ReferenceObject {
   $ref: string;
 }

package/src/options.ts

@@ -8,7 +8,7 @@
 import { Joi } from "@docusaurus/utils-validation";
 
 const sidebarOptions = Joi.object({
-  groupPathsBy: Joi.string().valid("tag"),
+  groupPathsBy: Joi.string().valid("tag", "tagGroup"),
   categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
@@ -37,6 +37,7 @@ export const OptionsSchema = Joi.object({
         showExtensions: Joi.boolean(),
         sidebarOptions: sidebarOptions,
         markdownGenerators: markdownGenerators,
+        showSchemas: Joi.boolean(),
         version: Joi.string().when("versions", {
           is: Joi.exist(),
           then: Joi.required(),

package/src/sidebars/index.ts

@@ -7,6 +7,7 @@
 
 import path from "path";
 
+import { ProcessedSidebarItem } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 import {
   ProcessedSidebar,
   SidebarItemCategory,
@@ -18,12 +19,13 @@ import clsx from "clsx";
 import { kebabCase } from "lodash";
 import uniq from "lodash/uniq";
 
-import { TagObject } from "../openapi/types";
+import { TagGroupObject, TagObject } from "../openapi/types";
 import type {
   SidebarOptions,
   APIOptions,
   ApiPageMetadata,
   ApiMetadata,
+  SchemaPageMetadata,
 } from "../types";
 
 function isApiItem(item: ApiMetadata): item is ApiMetadata {
@@ -34,6 +36,10 @@ function isInfoItem(item: ApiMetadata): item is ApiMetadata {
   return item.type === "info";
 }
 
+function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "schema";
+}
+
 function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
@@ -55,6 +61,7 @@ function groupByTags(
 
   const apiItems = items.filter(isApiItem);
   const infoItems = items.filter(isInfoItem);
+  const schemaItems = items.filter(isSchemaItem);
   const intros = infoItems.map((item: any) => {
     return {
       id: item.id,
@@ -80,28 +87,35 @@ function groupByTags(
       apiTags.push(tag.name!);
     }
   });
-  apiTags = uniq(apiTags.concat(operationTags));
+  // apiTags = uniq(apiTags.concat(operationTags));
 
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-  function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
+  function createDocItem(
+    item: ApiPageMetadata | SchemaPageMetadata
+  ): SidebarItemDoc {
     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"
+        ? clsx(
+            {
+              "menu__list-item--deprecated": item.api.deprecated,
+              "api-method": !!item.api.method,
+            },
+            item.api.method
+          )
+        : clsx({
+            "menu__list-item--deprecated": item.schema.deprecated,
+          });
     return {
       type: "doc" as const,
-      id:
-        basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
+      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
       label: (sidebar_label as string) ?? title ?? id,
       customProps: customProps,
-      className: clsx(
-        {
-          "menu__list-item--deprecated": item.api.deprecated,
-          "api-method": !!item.api.method,
-        },
-        item.api.method
-      ),
+      className: className ? className : undefined,
     };
   }
 
@@ -201,13 +215,26 @@ function groupByTags(
     ];
   }
 
+  let schemas: SidebarItemCategory[] = [];
+  if (schemaItems.length > 0) {
+    schemas = [
+      {
+        type: "category" as const,
+        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 as any);
   }
 
-  return [...tagged, ...untagged];
+  return [...tagged, ...untagged, ...schemas];
 }
 
 export default function generateSidebarSlice(
@@ -215,11 +242,38 @@ export default function generateSidebarSlice(
   options: APIOptions,
   api: ApiMetadata[],
   tags: TagObject[][],
-  docPath: string
+  docPath: string,
+  tagGroups?: TagGroupObject[]
 ) {
   let sidebarSlice: ProcessedSidebar = [];
 
-  if (sidebarOptions.groupPathsBy === "tag") {
+  if (sidebarOptions.groupPathsBy === "tagGroup") {
+    tagGroups?.forEach((tagGroup) => {
+      //filter tags only included in group
+      const filteredTags: TagObject[] = [];
+      tags[0].forEach((tag) => {
+        if (tagGroup.tags.includes(tag.name as string)) {
+          filteredTags.push(tag);
+        }
+      });
+
+      const groupCategory = {
+        type: "category" as const,
+        label: tagGroup.name,
+        collapsible: true,
+        collapsed: true,
+        items: groupByTags(
+          api as ApiPageMetadata[],
+          sidebarOptions,
+          options,
+          [filteredTags],
+          docPath
+        ),
+      } as ProcessedSidebarItem;
+
+      sidebarSlice.push(groupCategory);
+    });
+  } else if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,
@@ -228,5 +282,6 @@ export default function generateSidebarSlice(
       docPath
     );
   }
+
   return sidebarSlice;
 }

package/src/types.ts

@@ -10,6 +10,7 @@ import type Request from "@paloaltonetworks/postman-collection";
 import {
   InfoObject,
   OperationObject,
+  SchemaObject,
   SecuritySchemeObject,
   TagObject,
 } from "./openapi/types";
@@ -44,12 +45,14 @@ export interface APIOptions {
   };
   proxy?: string;
   markdownGenerators?: MarkdownGenerator;
+  showSchemas?: boolean;
 }
 
 export interface MarkdownGenerator {
   createApiPageMD?: (pageData: ApiPageMetadata) => string;
   createInfoPageMD?: (pageData: InfoPageMetadata) => string;
   createTagPageMD?: (pageData: TagPageMetadata) => string;
+  createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
 
 export interface SidebarOptions {
@@ -72,7 +75,11 @@ export interface LoadedContent {
   // loadedDocs: DocPageMetadata[]; TODO: cleanup
 }
 
-export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
+export type ApiMetadata =
+  | ApiPageMetadata
+  | InfoPageMetadata
+  | TagPageMetadata
+  | SchemaPageMetadata;
 
 export interface ApiMetadataBase {
   sidebar?: string;
@@ -131,6 +138,19 @@ export interface TagPageMetadata extends ApiMetadataBase {
   markdown?: string;
 }
 
+export interface SchemaPageMetadata extends ApiMetadataBase {
+  type: "schema";
+  schema: SchemaObject;
+  markdown?: string;
+}
+
+export interface TagGroupPageMetadata extends ApiMetadataBase {
+  type: "tagGroup";
+  name: string;
+  tags: TagObject[];
+  markdown?: string;
+}
+
 export type ApiInfo = InfoObject;
 
 export interface ApiNavLink {