docusaurus-plugin-openapi-docs 0.0.0-351 → 0.0.0-352

package/lib/index.js

@@ -25,7 +25,7 @@ function pluginOpenAPI(context, options) {
         const contentPath = path_1.default.resolve(siteDir, specPath);
         try {
             const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath, {});
-            const loadedApi = await (0, openapi_1.processOpenapiFiles)(openapiFiles);
+            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
@@ -38,7 +38,7 @@ function pluginOpenAPI(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, // TODO: find a better way to handle null
-                options, loadedApi);
+                options, loadedApi, tags);
                 const sidebarSliceTemplate = template
                     ? fs_1.default.readFileSync(template).toString()
                     : `module.exports = {{{slice}}};`;
@@ -59,7 +59,12 @@ function pluginOpenAPI(context, options) {
                 ? fs_1.default.readFileSync(template).toString()
                 : `---
 id: {{{id}}}
+{{^api}}
+sidebar_label: Introduction
+{{/api}}
+{{#api}}
 sidebar_label: {{{title}}}
+{{/api}}
 {{^api}}
 sidebar_position: 0
 {{/api}}
@@ -76,6 +81,23 @@ sidebar_class_name: "{{{api.method}}} api-method"
 ---
 
 {{{markdown}}}
+      `;
+            const infoMdTemplate = template
+                ? fs_1.default.readFileSync(template).toString()
+                : `---
+id: {{{id}}}
+sidebar_label: {{{title}}}
+hide_title: true
+---
+
+{{{markdown}}}
+
+\`\`\`mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+\`\`\`
       `;
             loadedApi.map(async (item) => {
                 const markdown = item.type === "api" ? (0, markdown_1.createApiPageMD)(item) : (0, markdown_1.createInfoPageMD)(item);
@@ -84,6 +106,7 @@ sidebar_class_name: "{{{api.method}}} api-method"
                     item.json = JSON.stringify(item.api);
                 }
                 const view = (0, mustache_1.render)(mdTemplate, item);
+                const utils = (0, mustache_1.render)(infoMdTemplate, item);
                 if (item.type === "api") {
                     if (!fs_1.default.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
                         try {
@@ -97,13 +120,15 @@ sidebar_class_name: "{{{api.method}}} api-method"
                 }
                 // TODO: determine if we actually want/need this
                 if (item.type === "info") {
-                    if (!fs_1.default.existsSync(`${outputDir}/index.api.mdx`)) {
+                    if (!fs_1.default.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
                         try {
-                            fs_1.default.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
-                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/index.api.mdx"`));
+                            (sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.useInfoAsCategoryLink)
+                                ? fs_1.default.writeFileSync(`${outputDir}/${item.id}.info.mdx`, utils, "utf8")
+                                : fs_1.default.writeFileSync(`${outputDir}/${item.id}.info.mdx`, view, "utf8");
+                            console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.info.mdx"`));
                         }
                         catch (err) {
-                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/index.api.mdx"`), chalk_1.default.yellow(err));
+                            console.error(chalk_1.default.red(`Failed to write "${outputDir}/${item.id}.info.mdx"`), chalk_1.default.yellow(err));
                         }
                     }
                 }
@@ -119,7 +144,7 @@ sidebar_class_name: "{{{api.method}}} api-method"
     async function cleanApiDocs(options) {
         const { outputDir } = options;
         const apiDir = path_1.default.join(siteDir, outputDir);
-        const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx"], {
+        const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx"], {
             cwd: path_1.default.resolve(apiDir),
         });
         const sidebarFile = await (0, utils_1.Globby)(["sidebar.js"], {

package/lib/openapi/openapi.d.ts

@@ -1,11 +1,12 @@
 import { ApiMetadata } from "../types";
-import { OpenApiObjectWithRef } from "./types";
+import { OpenApiObjectWithRef, TagObject } from "./types";
 interface OpenApiFiles {
     source: string;
     sourceDirName: string;
     data: OpenApiObjectWithRef;
 }
 export declare function readOpenapiFiles(openapiPath: string, _options: {}): Promise<OpenApiFiles[]>;
-export declare function processOpenapiFiles(files: OpenApiFiles[]): Promise<ApiMetadata[]>;
-export declare function processOpenapiFile(openapiDataWithRefs: OpenApiObjectWithRef): Promise<ApiMetadata[]>;
+export declare function processOpenapiFiles(files: OpenApiFiles[]): Promise<[ApiMetadata[], TagObject[]]>;
+export declare function processOpenapiFile(openapiDataWithRefs: OpenApiObjectWithRef): Promise<[ApiMetadata[], TagObject[]]>;
+export declare function getTagDisplayName(tagName: string, tags: TagObject[]): string;
 export {};

package/lib/openapi/openapi.js

@@ -9,7 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processOpenapiFile = exports.processOpenapiFiles = exports.readOpenapiFiles = void 0;
+exports.getTagDisplayName = exports.processOpenapiFile = exports.processOpenapiFiles = exports.readOpenapiFiles = void 0;
 const path_1 = __importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
 const openapi_to_postmanv2_1 = __importDefault(require("@paloaltonetworks/openapi-to-postmanv2"));
@@ -64,22 +64,24 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
     // TODO: Find a better way to handle this
     let items = [];
     // Only create an info page if we have a description.
     if (openapiData.info.description) {
+        const infoId = (0, lodash_1.kebabCase)(openapiData.info.title);
         const infoPage = {
             type: "info",
-            id: "introduction",
-            unversionedId: "introduction",
-            title: "Introduction",
+            id: infoId,
+            unversionedId: infoId,
+            title: openapiData.info.title,
             description: openapiData.info.description,
-            slug: "/introduction",
+            slug: "/" + infoId,
             frontMatter: {},
             info: {
                 ...openapiData.info,
-                title: (_a = openapiData.info.title) !== null && _a !== void 0 ? _a : "Introduction",
+                tags: (_a = openapiData.tags) === null || _a === void 0 ? void 0 : _a.map((tagName) => { var _a; return getTagDisplayName(tagName.name, (_a = openapiData.tags) !== null && _a !== void 0 ? _a : []); }),
+                title: (_b = openapiData.info.title) !== null && _b !== void 0 ? _b : "Introduction",
             },
         };
         items.push(infoPage);
@@ -87,16 +89,16 @@ function createItems(openapiData) {
     for (let [path, pathObject] of Object.entries(openapiData.paths)) {
         const { $ref, description, parameters, servers, summary, ...rest } = pathObject;
         for (let [method, operationObject] of Object.entries({ ...rest })) {
-            const title = (_c = (_b = operationObject.summary) !== null && _b !== void 0 ? _b : operationObject.operationId) !== null && _c !== void 0 ? _c : "Missing summary";
+            const title = (_d = (_c = operationObject.summary) !== null && _c !== void 0 ? _c : operationObject.operationId) !== null && _d !== void 0 ? _d : "Missing summary";
             if (operationObject.description === undefined) {
                 operationObject.description =
-                    (_e = (_d = operationObject.summary) !== null && _d !== void 0 ? _d : operationObject.operationId) !== null && _e !== void 0 ? _e : "";
+                    (_f = (_e = operationObject.summary) !== null && _e !== void 0 ? _e : operationObject.operationId) !== null && _f !== void 0 ? _f : "";
             }
             const baseId = (0, lodash_1.kebabCase)(title);
-            const servers = (_g = (_f = operationObject.servers) !== null && _f !== void 0 ? _f : pathObject.servers) !== null && _g !== void 0 ? _g : openapiData.servers;
-            const security = (_h = operationObject.security) !== null && _h !== void 0 ? _h : openapiData.security;
+            const servers = (_h = (_g = operationObject.servers) !== null && _g !== void 0 ? _g : pathObject.servers) !== null && _h !== void 0 ? _h : openapiData.servers;
+            const security = (_j = operationObject.security) !== null && _j !== void 0 ? _j : openapiData.security;
             // Add security schemes so we know how to handle security.
-            const securitySchemes = (_j = openapiData.components) === null || _j === void 0 ? void 0 : _j.securitySchemes;
+            const securitySchemes = (_k = openapiData.components) === null || _k === void 0 ? void 0 : _k.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)) {
@@ -106,7 +108,7 @@ function createItems(openapiData) {
                 }
             }
             let jsonRequestBodyExample;
-            const body = (_l = (_k = operationObject.requestBody) === null || _k === void 0 ? void 0 : _k.content) === null || _l === void 0 ? void 0 : _l["application/json"];
+            const body = (_m = (_l = operationObject.requestBody) === null || _l === void 0 ? void 0 : _l.content) === null || _m === void 0 ? void 0 : _m["application/json"];
             if (body === null || body === void 0 ? void 0 : body.schema) {
                 jsonRequestBodyExample = (0, createExample_1.sampleFromSchema)(body.schema);
             }
@@ -122,7 +124,7 @@ function createItems(openapiData) {
                 frontMatter: {},
                 api: {
                     ...defaults,
-                    tags: (_m = operationObject.tags) === null || _m === void 0 ? void 0 : _m.map((tagName) => { var _a; return getTagDisplayName(tagName, (_a = openapiData.tags) !== null && _a !== void 0 ? _a : []); }),
+                    tags: (_o = operationObject.tags) === null || _o === void 0 ? void 0 : _o.map((tagName) => { var _a; return getTagDisplayName(tagName, (_a = openapiData.tags) !== null && _a !== void 0 ? _a : []); }),
                     method,
                     path,
                     servers,
@@ -192,14 +194,23 @@ async function readOpenapiFiles(openapiPath, _options) {
 exports.readOpenapiFiles = readOpenapiFiles;
 async function processOpenapiFiles(files) {
     const promises = files.map(async (file) => {
-        const items = await processOpenapiFile(file.data);
-        return items.map((item) => ({
+        const processedFile = await processOpenapiFile(file.data);
+        const itemsObjectsArray = processedFile[0].map((item) => ({
             ...item,
         }));
+        const tags = processedFile[1];
+        return [itemsObjectsArray, tags];
     });
     const metadata = await Promise.all(promises);
-    const items = metadata.flat();
-    return items;
+    const items = metadata
+        .map(function (x) {
+        return x[0];
+    })
+        .flat();
+    const tags = metadata.map(function (x) {
+        return x[1];
+    });
+    return [items, tags];
 }
 exports.processOpenapiFiles = processOpenapiFiles;
 async function processOpenapiFile(openapiDataWithRefs) {
@@ -207,7 +218,11 @@ async function processOpenapiFile(openapiDataWithRefs) {
     const postmanCollection = await createPostmanCollection(openapiData);
     const items = createItems(openapiData);
     bindCollectionToApiItems(items, postmanCollection);
-    return items;
+    let tags = [];
+    if (openapiData.tags !== undefined) {
+        tags = openapiData.tags;
+    }
+    return [items, tags];
 }
 exports.processOpenapiFile = processOpenapiFile;
 // order for picking items as a display name of tags
@@ -229,3 +244,4 @@ function getTagDisplayName(tagName, tags) {
     // always default to the tagName
     return tagName;
 }
+exports.getTagDisplayName = getTagDisplayName;

package/lib/openapi/types.d.ts

@@ -29,6 +29,7 @@ export interface InfoObject {
     contact?: ContactObject;
     license?: LicenseObject;
     version: string;
+    tags?: String[];
 }
 export interface ContactObject {
     name?: string;
@@ -237,7 +238,7 @@ export interface LinkObject {
 export declare type HeaderObject = Omit<ParameterObject, "name" | "in">;
 export declare type HeaderObjectWithRef = Omit<ParameterObjectWithRef, "name" | "in">;
 export interface TagObject {
-    name: string;
+    name?: string;
     description?: string;
     externalDocs?: ExternalDocumentationObject;
     "x-displayName"?: string;

package/lib/sidebars/index.d.ts

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

package/lib/sidebars/index.js

@@ -10,25 +10,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const clsx_1 = __importDefault(require("clsx"));
+const lodash_1 = require("lodash");
 const uniq_1 = __importDefault(require("lodash/uniq"));
 function isApiItem(item) {
     return item.type === "api";
 }
-function groupByTags(items, sidebarOptions, options) {
-    // TODO: Figure out how to handle these
-    // const intros = items.filter(isInfoItem).map((item) => {
-    //   return {
-    //     type: "link" as const,
-    //     label: item.title,
-    //     href: item.permalink,
-    //     docId: item.id,
-    //   };
-    // });
+function isInfoItem(item) {
+    return item.type === "info";
+}
+function groupByTags(items, sidebarOptions, options, tags) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
+    const linkSource = categoryLinkSource !== null && categoryLinkSource !== void 0 ? categoryLinkSource : "tag";
     const apiItems = items.filter(isApiItem);
+    const infoItems = items.filter(isInfoItem);
+    const intros = infoItems.map((item) => {
+        return {
+            id: item.id,
+            title: item.title,
+            description: item.description,
+            tags: item.info.tags,
+        };
+    });
     // TODO: make sure we only take the first tag
-    const tags = (0, uniq_1.default)(apiItems
+    const tags_ = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
     // TODO: optimize this or make it a function
@@ -51,11 +56,47 @@ function groupByTags(items, sidebarOptions, options) {
             }, item.api.method),
         };
     }
-    const tagged = tags
+    let introDoc = undefined;
+    if (linkSource === "info") {
+        const infoItem = infoItems[0];
+        const id = infoItem.id;
+        introDoc = {
+            type: "doc",
+            id: `${basePath}/${id}`,
+        };
+    }
+    const tagged = tags_
         .map((tag) => {
+        // TODO: should we also use the info.title as generated-index title?
+        const infoObject = intros.find((i) => i.tags.includes(tag));
+        const tagObject = tags.flat().find((t) => {
+            var _a;
+            return (_a = (tag === t.name || tag === t["x-displayName"])) !== null && _a !== void 0 ? _a : {
+                name: tag,
+                description: `${tag} Index`,
+            };
+        });
+        // TODO: perhaps move all this into a getLinkConfig() function
+        let linkConfig = undefined;
+        if (infoObject !== undefined && linkSource === "info") {
+            linkConfig = {
+                type: "doc",
+                id: `${basePath}/${infoObject.id}`,
+            };
+        }
+        if (tagObject !== undefined && linkSource === "tag") {
+            const linkDescription = tagObject === null || tagObject === void 0 ? void 0 : tagObject.description;
+            linkConfig = {
+                type: "generated-index",
+                title: tag,
+                description: linkDescription,
+                slug: "/category/" + (0, lodash_1.kebabCase)(tag),
+            };
+        }
         return {
             type: "category",
             label: tag,
+            link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
             items: apiItems
@@ -64,25 +105,28 @@ function groupByTags(items, sidebarOptions, options) {
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
+    // TODO: determine how we want to handle these
     // const untagged = [
-    //   // TODO: determine if needed and how
     //   {
     //     type: "category" as const,
     //     label: "UNTAGGED",
-    //     // collapsible: options.sidebarCollapsible, TODO: add option
-    //     // collapsed: options.sidebarCollapsed, TODO: add option
+    //     collapsible: sidebarCollapsible,
+    //     collapsed: sidebarCollapsed,
     //     items: apiItems
-    //       //@ts-ignore
     //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
     //       .map(createDocItem),
     //   },
     // ];
+    // Shift intro doc to top of sidebar
+    if (introDoc && linkSource === "info") {
+        tagged.unshift(introDoc);
+    }
     return [...tagged];
 }
-function generateSidebarSlice(sidebarOptions, options, api) {
+function generateSidebarSlice(sidebarOptions, options, api, tags) {
     let sidebarSlice = [];
     if (sidebarOptions.groupPathsBy === "tags") {
-        sidebarSlice = groupByTags(api, sidebarOptions, options);
+        sidebarSlice = groupByTags(api, sidebarOptions, options, tags);
     }
     return sidebarSlice;
 }

package/lib/types.d.ts

@@ -60,6 +60,8 @@ export interface ApiNavLink {
 }
 export interface SidebarOptions {
     groupPathsBy?: string;
+    useInfoAsCategoryLink?: boolean;
+    categoryLinkSource?: string;
     customProps?: {
         [key: string]: unknown;
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-351",
+  "version": "0.0.0-352",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "475483bcb20b232da5c12ee23c48855dd32ba0d8"
+  "gitHead": "dc9b85400c4cf3f675641234bf38c398b5ba9dd0"
 }

package/src/index.ts

@@ -32,8 +32,7 @@ export default function pluginOpenAPI(
 
     try {
       const openapiFiles = await readOpenapiFiles(contentPath, {});
-      const loadedApi = await processOpenapiFiles(openapiFiles);
-
+      const [loadedApi, tags] = await processOpenapiFiles(openapiFiles);
       if (!fs.existsSync(outputDir)) {
         try {
           fs.mkdirSync(outputDir, { recursive: true });
@@ -51,7 +50,8 @@ export default function pluginOpenAPI(
         const sidebarSlice = generateSidebarSlice(
           sidebarOptions!, // TODO: find a better way to handle null
           options,
-          loadedApi
+          loadedApi,
+          tags
         );
 
         const sidebarSliceTemplate = template
@@ -81,7 +81,12 @@ export default function pluginOpenAPI(
         ? fs.readFileSync(template).toString()
         : `---
 id: {{{id}}}
+{{^api}}
+sidebar_label: Introduction
+{{/api}}
+{{#api}}
 sidebar_label: {{{title}}}
+{{/api}}
 {{^api}}
 sidebar_position: 0
 {{/api}}
@@ -100,6 +105,24 @@ sidebar_class_name: "{{{api.method}}} api-method"
 {{{markdown}}}
       `;
 
+      const infoMdTemplate = template
+        ? fs.readFileSync(template).toString()
+        : `---
+id: {{{id}}}
+sidebar_label: {{{title}}}
+hide_title: true
+---
+
+{{{markdown}}}
+
+\`\`\`mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+\`\`\`
+      `;
+
       loadedApi.map(async (item) => {
         const markdown =
           item.type === "api" ? createApiPageMD(item) : createInfoPageMD(item);
@@ -108,6 +131,7 @@ sidebar_class_name: "{{{api.method}}} api-method"
           item.json = JSON.stringify(item.api);
         }
         const view = render(mdTemplate, item);
+        const utils = render(infoMdTemplate, item);
 
         if (item.type === "api") {
           if (!fs.existsSync(`${outputDir}/${item.id}.api.mdx`)) {
@@ -129,15 +153,27 @@ sidebar_class_name: "{{{api.method}}} api-method"
 
         // TODO: determine if we actually want/need this
         if (item.type === "info") {
-          if (!fs.existsSync(`${outputDir}/index.api.mdx`)) {
+          if (!fs.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
             try {
-              fs.writeFileSync(`${outputDir}/index.api.mdx`, view, "utf8");
+              sidebarOptions?.useInfoAsCategoryLink
+                ? fs.writeFileSync(
+                    `${outputDir}/${item.id}.info.mdx`,
+                    utils,
+                    "utf8"
+                  )
+                : fs.writeFileSync(
+                    `${outputDir}/${item.id}.info.mdx`,
+                    view,
+                    "utf8"
+                  );
               console.log(
-                chalk.green(`Successfully created "${outputDir}/index.api.mdx"`)
+                chalk.green(
+                  `Successfully created "${outputDir}/${item.id}.info.mdx"`
+                )
               );
             } catch (err) {
               console.error(
-                chalk.red(`Failed to write "${outputDir}/index.api.mdx"`),
+                chalk.red(`Failed to write "${outputDir}/${item.id}.info.mdx"`),
                 chalk.yellow(err)
               );
             }
@@ -155,7 +191,7 @@ sidebar_class_name: "{{{api.method}}} api-method"
   async function cleanApiDocs(options: APIOptions) {
     const { outputDir } = options;
     const apiDir = path.join(siteDir, outputDir);
-    const apiMdxFiles = await Globby(["*.api.mdx"], {
+    const apiMdxFiles = await Globby(["*.api.mdx", "*.info.mdx"], {
       cwd: path.resolve(apiDir),
     });
     const sidebarFile = await Globby(["sidebar.js"], {

package/src/openapi/openapi.ts

@@ -81,16 +81,20 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
 
   // Only create an info page if we have a description.
   if (openapiData.info.description) {
+    const infoId = kebabCase(openapiData.info.title);
     const infoPage: PartialPage<InfoPageMetadata> = {
       type: "info",
-      id: "introduction",
-      unversionedId: "introduction",
-      title: "Introduction",
+      id: infoId,
+      unversionedId: infoId,
+      title: openapiData.info.title,
       description: openapiData.info.description,
-      slug: "/introduction",
+      slug: "/" + infoId,
       frontMatter: {},
       info: {
         ...openapiData.info,
+        tags: openapiData.tags?.map((tagName) =>
+          getTagDisplayName(tagName.name!, openapiData.tags ?? [])
+        ),
         title: openapiData.info.title ?? "Introduction",
       },
     };
@@ -245,34 +249,47 @@ export async function readOpenapiFiles(
 
 export async function processOpenapiFiles(
   files: OpenApiFiles[]
-): Promise<ApiMetadata[]> {
+): Promise<[ApiMetadata[], TagObject[]]> {
   const promises = files.map(async (file) => {
-    const items = await processOpenapiFile(file.data);
-    return items.map((item) => ({
+    const processedFile = await processOpenapiFile(file.data);
+    const itemsObjectsArray = processedFile[0].map((item) => ({
       ...item,
     }));
+    const tags = processedFile[1];
+    return [itemsObjectsArray, tags];
   });
   const metadata = await Promise.all(promises);
-  const items = metadata.flat();
-  return items;
+  const items = metadata
+    .map(function (x) {
+      return x[0];
+    })
+    .flat();
+  const tags = metadata.map(function (x) {
+    return x[1];
+  });
+  return [items as ApiMetadata[], tags as TagObject[]];
 }
 
 export async function processOpenapiFile(
   openapiDataWithRefs: OpenApiObjectWithRef
-): Promise<ApiMetadata[]> {
+): Promise<[ApiMetadata[], TagObject[]]> {
   const openapiData = await resolveRefs(openapiDataWithRefs);
   const postmanCollection = await createPostmanCollection(openapiData);
   const items = createItems(openapiData);
 
   bindCollectionToApiItems(items, postmanCollection);
 
-  return items;
+  let tags: TagObject[] = [];
+  if (openapiData.tags !== undefined) {
+    tags = openapiData.tags;
+  }
+  return [items, tags];
 }
 
 // order for picking items as a display name of tags
 const tagDisplayNameProperties = ["x-displayName", "name"] as const;
 
-function getTagDisplayName(tagName: string, tags: TagObject[]): string {
+export function getTagDisplayName(tagName: string, tags: TagObject[]): string {
   // find the very own tagObject
   const tagObject = tags.find((tagObject) => tagObject.name === tagName) ?? {
     // if none found, just fake one

package/src/openapi/types.ts

@@ -40,6 +40,7 @@ export interface InfoObject {
   contact?: ContactObject;
   license?: LicenseObject;
   version: string;
+  tags?: String[];
 }
 
 export interface ContactObject {
@@ -294,7 +295,7 @@ export type HeaderObject = Omit<ParameterObject, "name" | "in">;
 export type HeaderObjectWithRef = Omit<ParameterObjectWithRef, "name" | "in">;
 
 export interface TagObject {
-  name: string;
+  name?: string;
   description?: string;
   externalDocs?: ExternalDocumentationObject;
   "x-displayName"?: string;

package/src/sidebars/index.ts

@@ -7,11 +7,14 @@
 
 import {
   ProcessedSidebar,
+  SidebarItemCategoryLinkConfig,
   SidebarItemDoc,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import clsx from "clsx";
+import { kebabCase } from "lodash";
 import uniq from "lodash/uniq";
 
+import { TagObject } from "../openapi/types";
 import type {
   SidebarOptions,
   APIOptions,
@@ -23,28 +26,38 @@ function isApiItem(item: ApiMetadata): item is ApiMetadata {
   return item.type === "api";
 }
 
+function isInfoItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "info";
+}
+
 function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
-  options: APIOptions
+  options: APIOptions,
+  tags: TagObject[]
 ): ProcessedSidebar {
-  // TODO: Figure out how to handle these
-  // const intros = items.filter(isInfoItem).map((item) => {
-  //   return {
-  //     type: "link" as const,
-  //     label: item.title,
-  //     href: item.permalink,
-  //     docId: item.id,
-  //   };
-  // });
-
   const { outputDir } = options;
-  const { sidebarCollapsed, sidebarCollapsible, customProps } = sidebarOptions;
+  const {
+    sidebarCollapsed,
+    sidebarCollapsible,
+    customProps,
+    categoryLinkSource,
+  } = sidebarOptions;
+  const linkSource = categoryLinkSource ?? "tag";
 
   const apiItems = items.filter(isApiItem);
+  const infoItems = items.filter(isInfoItem);
+  const intros = infoItems.map((item: any) => {
+    return {
+      id: item.id,
+      title: item.title,
+      description: item.description,
+      tags: item.info.tags,
+    };
+  });
 
   // TODO: make sure we only take the first tag
-  const tags = uniq(
+  const tags_ = uniq(
     apiItems
       .flatMap((item) => item.api.tags)
       .filter((item): item is string => !!item)
@@ -74,11 +87,51 @@ function groupByTags(
     };
   }
 
-  const tagged = tags
+  let introDoc = undefined;
+  if (linkSource === "info") {
+    const infoItem = infoItems[0];
+    const id = infoItem.id;
+    introDoc = {
+      type: "doc" as const,
+      id: `${basePath}/${id}`,
+    };
+  }
+
+  const tagged = tags_
     .map((tag) => {
+      // TODO: should we also use the info.title as generated-index title?
+      const infoObject = intros.find((i) => i.tags.includes(tag));
+      const tagObject = tags.flat().find(
+        (t) =>
+          (tag === t.name || tag === t["x-displayName"]) ?? {
+            name: tag,
+            description: `${tag} Index`,
+          }
+      );
+
+      // TODO: perhaps move all this into a getLinkConfig() function
+      let linkConfig = undefined;
+      if (infoObject !== undefined && linkSource === "info") {
+        linkConfig = {
+          type: "doc",
+          id: `${basePath}/${infoObject.id}`,
+        } as SidebarItemCategoryLinkConfig;
+      }
+
+      if (tagObject !== undefined && linkSource === "tag") {
+        const linkDescription = tagObject?.description;
+        linkConfig = {
+          type: "generated-index" as "generated-index",
+          title: tag,
+          description: linkDescription,
+          slug: "/category/" + kebabCase(tag),
+        } as SidebarItemCategoryLinkConfig;
+      }
+
       return {
         type: "category" as const,
         label: tag,
+        link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
         items: apiItems
@@ -88,33 +141,40 @@ function groupByTags(
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
 
+  // TODO: determine how we want to handle these
   // const untagged = [
-  //   // TODO: determine if needed and how
   //   {
   //     type: "category" as const,
   //     label: "UNTAGGED",
-  //     // collapsible: options.sidebarCollapsible, TODO: add option
-  //     // collapsed: options.sidebarCollapsed, TODO: add option
+  //     collapsible: sidebarCollapsible,
+  //     collapsed: sidebarCollapsed,
   //     items: apiItems
-  //       //@ts-ignore
   //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
   //       .map(createDocItem),
   //   },
   // ];
+
+  // Shift intro doc to top of sidebar
+  if (introDoc && linkSource === "info") {
+    tagged.unshift(introDoc as any);
+  }
+
   return [...tagged];
 }
 
 export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  api: ApiMetadata[]
+  api: ApiMetadata[],
+  tags: TagObject[]
 ) {
   let sidebarSlice: ProcessedSidebar = [];
   if (sidebarOptions.groupPathsBy === "tags") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,
-      options
+      options,
+      tags
     );
   }
   return sidebarSlice;

package/src/types.ts

@@ -90,6 +90,8 @@ export interface ApiNavLink {
 
 export interface SidebarOptions {
   groupPathsBy?: string;
+  useInfoAsCategoryLink?: boolean; // TODO: confirm name of option
+  categoryLinkSource?: string;
   customProps?: { [key: string]: unknown };
   sidebarCollapsible?: boolean;
   sidebarCollapsed?: boolean;