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

package/README.md

@@ -110,12 +110,13 @@ Here is an example of properly configuring your `docusaurus.config.js` file for
 
 `sidebarOptions` can be configured with the following options:
 
-| Name                 | Type      | Default | Description                                                                                                                         |
-| -------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `groupPathsBy`       | `string`  | `null`  | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by "tags". |
-| `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                              |
-| `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                |
-| `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                    |
+| Name                 | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `groupPathsBy`       | `string`  | `null`  | Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by "tags".                                                                                                                                                                                                                                                                                                                  |
+| `categoryLinkSource` | `string`  | `null`  | Defines what source to use for rendering category link pages when grouping paths by tag. <br/></br>The supported options are as follows: <br/></br> `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. <br/><br/>`info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). |
+| `sidebarCollapsible` | `boolean` | `true`  | Whether sidebar categories are collapsible by default.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `sidebarCollapsed`   | `boolean` | `true`  | Whether sidebar categories are collapsed by default.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `customProps`        | `object`  | `null`  | Additional props for customizing a sidebar item.                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 > Note: You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
 

package/lib/index.js

@@ -122,7 +122,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
                 if (item.type === "info") {
                     if (!fs_1.default.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
                         try {
-                            (sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.useInfoAsCategoryLink)
+                            (sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "info" // Only use utils template if set to "info"
                                 ? 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"`));

package/lib/markdown/createContactInfo.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createContactInfo = void 0;
 const utils_1 = require("./utils");
 function createContactInfo(contact) {
-    if (!contact)
+    if (!contact || !Object.keys(contact).length)
         return "";
     const { name, url, email } = contact;
     return (0, utils_1.create)("div", {
@@ -27,14 +27,14 @@ function createContactInfo(contact) {
             }),
             (0, utils_1.create)("span", {
                 children: [
-                    `${name}: `,
-                    (0, utils_1.create)("a", {
+                    (0, utils_1.guard)(name, () => `${name}: `),
+                    (0, utils_1.guard)(email, () => (0, utils_1.create)("a", {
                         href: `mailto:${email}`,
                         children: `${email}`,
-                    }),
+                    })),
                 ],
             }),
-            (0, utils_1.create)("span", {
+            (0, utils_1.guard)(url, () => (0, utils_1.create)("span", {
                 children: [
                     "URL: ",
                     (0, utils_1.create)("a", {
@@ -42,7 +42,7 @@ function createContactInfo(contact) {
                         children: `${url}`,
                     }),
                 ],
-            }),
+            })),
         ],
     });
 }

package/lib/markdown/createLicense.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLicense = void 0;
 const utils_1 = require("./utils");
 function createLicense(license) {
-    if (!license)
+    if (!license || !Object.keys(license).length)
         return "";
     const { name, url } = license;
     return (0, utils_1.create)("div", {
@@ -23,10 +23,10 @@ function createLicense(license) {
                 },
                 children: "License",
             }),
-            (0, utils_1.create)("a", {
+            (0, utils_1.guard)(url, () => (0, utils_1.create)("a", {
                 href: url,
-                children: name,
-            }),
+                children: name !== null && name !== void 0 ? name : url,
+            })),
         ],
     });
 }

package/lib/markdown/createTermsOfService.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTermsOfService = void 0;
 const utils_1 = require("./utils");
 function createTermsOfService(termsOfService) {
-    if (!createTermsOfService)
+    if (!termsOfService)
         return "";
     return (0, utils_1.create)("div", {
         style: {

package/lib/sidebars/index.js

@@ -21,7 +21,6 @@ function isInfoItem(item) {
 function groupByTags(items, sidebarOptions, options, tags) {
     const { outputDir } = options;
     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) => {
@@ -33,7 +32,7 @@ function groupByTags(items, sidebarOptions, options, tags) {
         };
     });
     // TODO: make sure we only take the first tag
-    const tags_ = (0, uniq_1.default)(apiItems
+    const apiTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
     // TODO: optimize this or make it a function
@@ -56,18 +55,18 @@ function groupByTags(items, sidebarOptions, options, tags) {
             }, item.api.method),
         };
     }
-    let introDoc = undefined;
-    if (linkSource === "info") {
+    let rootIntroDoc = undefined;
+    if (infoItems.length === 1) {
         const infoItem = infoItems[0];
         const id = infoItem.id;
-        introDoc = {
+        rootIntroDoc = {
             type: "doc",
             id: `${basePath}/${id}`,
         };
     }
-    const tagged = tags_
+    const tagged = apiTags
         .map((tag) => {
-        // TODO: should we also use the info.title as generated-index title?
+        // Map info object to tag
         const infoObject = intros.find((i) => i.tags.includes(tag));
         const tagObject = tags.flat().find((t) => {
             var _a;
@@ -76,15 +75,16 @@ function groupByTags(items, sidebarOptions, options, tags) {
                 description: `${tag} Index`,
             };
         });
-        // TODO: perhaps move all this into a getLinkConfig() function
+        // TODO: perhaps move this into a getLinkConfig() function
         let linkConfig = undefined;
-        if (infoObject !== undefined && linkSource === "info") {
+        if (infoObject !== undefined && categoryLinkSource === "info") {
             linkConfig = {
                 type: "doc",
                 id: `${basePath}/${infoObject.id}`,
             };
         }
-        if (tagObject !== undefined && linkSource === "tag") {
+        // TODO: perhaps move this into a getLinkConfig() function
+        if (tagObject !== undefined && categoryLinkSource === "tag") {
             const linkDescription = tagObject === null || tagObject === void 0 ? void 0 : tagObject.description;
             linkConfig = {
                 type: "generated-index",
@@ -93,6 +93,14 @@ function groupByTags(items, sidebarOptions, options, tags) {
                 slug: "/category/" + (0, lodash_1.kebabCase)(tag),
             };
         }
+        // Default behavior
+        if (categoryLinkSource === undefined) {
+            linkConfig = {
+                type: "generated-index",
+                title: tag,
+                slug: "/category/" + (0, lodash_1.kebabCase)(tag),
+            };
+        }
         return {
             type: "category",
             label: tag,
@@ -117,9 +125,10 @@ function groupByTags(items, sidebarOptions, options, tags) {
     //       .map(createDocItem),
     //   },
     // ];
-    // Shift intro doc to top of sidebar
-    if (introDoc && linkSource === "info") {
-        tagged.unshift(introDoc);
+    // Shift root intro doc to top of sidebar
+    // TODO: Add input validation for categoryLinkSource options
+    if (rootIntroDoc && categoryLinkSource !== "info") {
+        tagged.unshift(rootIntroDoc);
     }
     return [...tagged];
 }

package/lib/types.d.ts

@@ -60,7 +60,6 @@ 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-352",
+  "version": "0.0.0-355",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "dc9b85400c4cf3f675641234bf38c398b5ba9dd0"
+  "gitHead": "7b46d0266d04d1e64a5ae9025a2dd3452bca492c"
 }

package/src/index.ts

@@ -155,7 +155,7 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         if (item.type === "info") {
           if (!fs.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
             try {
-              sidebarOptions?.useInfoAsCategoryLink
+              sidebarOptions?.categoryLinkSource === "info" // Only use utils template if set to "info"
                 ? fs.writeFileSync(
                     `${outputDir}/${item.id}.info.mdx`,
                     utils,

package/src/markdown/createContactInfo.ts

@@ -6,10 +6,10 @@
  * ========================================================================== */
 
 import { ContactObject } from "../openapi/types";
-import { create } from "./utils";
+import { create, guard } from "./utils";
 
 export function createContactInfo(contact: ContactObject) {
-  if (!contact) return "";
+  if (!contact || !Object.keys(contact).length) return "";
   const { name, url, email } = contact;
 
   return create("div", {
@@ -27,22 +27,26 @@ export function createContactInfo(contact: ContactObject) {
       }),
       create("span", {
         children: [
-          `${name}: `,
-          create("a", {
-            href: `mailto:${email}`,
-            children: `${email}`,
-          }),
-        ],
-      }),
-      create("span", {
-        children: [
-          "URL: ",
-          create("a", {
-            href: `${url}`,
-            children: `${url}`,
-          }),
+          guard(name, () => `${name}: `),
+          guard(email, () =>
+            create("a", {
+              href: `mailto:${email}`,
+              children: `${email}`,
+            })
+          ),
         ],
       }),
+      guard(url, () =>
+        create("span", {
+          children: [
+            "URL: ",
+            create("a", {
+              href: `${url}`,
+              children: `${url}`,
+            }),
+          ],
+        })
+      ),
     ],
   });
 }

package/src/markdown/createLicense.ts

@@ -6,10 +6,10 @@
  * ========================================================================== */
 
 import { LicenseObject } from "../openapi/types";
-import { create } from "./utils";
+import { create, guard } from "./utils";
 
 export function createLicense(license: LicenseObject) {
-  if (!license) return "";
+  if (!license || !Object.keys(license).length) return "";
   const { name, url } = license;
 
   return create("div", {
@@ -23,10 +23,12 @@ export function createLicense(license: LicenseObject) {
         },
         children: "License",
       }),
-      create("a", {
-        href: url,
-        children: name,
-      }),
+      guard(url, () =>
+        create("a", {
+          href: url,
+          children: name ?? url,
+        })
+      ),
     ],
   });
 }

package/src/markdown/createTermsOfService.ts

@@ -8,7 +8,7 @@
 import { create } from "./utils";
 
 export function createTermsOfService(termsOfService: string | undefined) {
-  if (!createTermsOfService) return "";
+  if (!termsOfService) return "";
 
   return create("div", {
     style: {

package/src/sidebars/index.ts

@@ -43,7 +43,6 @@ function groupByTags(
     customProps,
     categoryLinkSource,
   } = sidebarOptions;
-  const linkSource = categoryLinkSource ?? "tag";
 
   const apiItems = items.filter(isApiItem);
   const infoItems = items.filter(isInfoItem);
@@ -57,7 +56,7 @@ function groupByTags(
   });
 
   // TODO: make sure we only take the first tag
-  const tags_ = uniq(
+  const apiTags = uniq(
     apiItems
       .flatMap((item) => item.api.tags)
       .filter((item): item is string => !!item)
@@ -87,19 +86,19 @@ function groupByTags(
     };
   }
 
-  let introDoc = undefined;
-  if (linkSource === "info") {
+  let rootIntroDoc = undefined;
+  if (infoItems.length === 1) {
     const infoItem = infoItems[0];
     const id = infoItem.id;
-    introDoc = {
+    rootIntroDoc = {
       type: "doc" as const,
       id: `${basePath}/${id}`,
     };
   }
 
-  const tagged = tags_
+  const tagged = apiTags
     .map((tag) => {
-      // TODO: should we also use the info.title as generated-index title?
+      // Map info object to tag
       const infoObject = intros.find((i) => i.tags.includes(tag));
       const tagObject = tags.flat().find(
         (t) =>
@@ -109,16 +108,17 @@ function groupByTags(
           }
       );
 
-      // TODO: perhaps move all this into a getLinkConfig() function
+      // TODO: perhaps move this into a getLinkConfig() function
       let linkConfig = undefined;
-      if (infoObject !== undefined && linkSource === "info") {
+      if (infoObject !== undefined && categoryLinkSource === "info") {
         linkConfig = {
           type: "doc",
           id: `${basePath}/${infoObject.id}`,
         } as SidebarItemCategoryLinkConfig;
       }
 
-      if (tagObject !== undefined && linkSource === "tag") {
+      // TODO: perhaps move this into a getLinkConfig() function
+      if (tagObject !== undefined && categoryLinkSource === "tag") {
         const linkDescription = tagObject?.description;
         linkConfig = {
           type: "generated-index" as "generated-index",
@@ -128,6 +128,15 @@ function groupByTags(
         } as SidebarItemCategoryLinkConfig;
       }
 
+      // Default behavior
+      if (categoryLinkSource === undefined) {
+        linkConfig = {
+          type: "generated-index" as "generated-index",
+          title: tag,
+          slug: "/category/" + kebabCase(tag),
+        } as SidebarItemCategoryLinkConfig;
+      }
+
       return {
         type: "category" as const,
         label: tag,
@@ -154,9 +163,10 @@ function groupByTags(
   //   },
   // ];
 
-  // Shift intro doc to top of sidebar
-  if (introDoc && linkSource === "info") {
-    tagged.unshift(introDoc as any);
+  // 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];

package/src/types.ts

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