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

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/markdown/createContactInfo.ts

@@ -0,0 +1,48 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { ContactObject } from "../openapi/types";
+import { create } from "./utils";
+
+export function createContactInfo(contact: ContactObject) {
+  if (!contact) return "";
+  const { name, url, email } = contact;
+
+  return create("div", {
+    style: {
+      display: "flex",
+      flexDirection: "column",
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "Contact",
+      }),
+      create("span", {
+        children: [
+          `${name}: `,
+          create("a", {
+            href: `mailto:${email}`,
+            children: `${email}`,
+          }),
+        ],
+      }),
+      create("span", {
+        children: [
+          "URL: ",
+          create("a", {
+            href: `${url}`,
+            children: `${url}`,
+          }),
+        ],
+      }),
+    ],
+  });
+}

package/src/markdown/createLicense.ts

@@ -0,0 +1,32 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { LicenseObject } from "../openapi/types";
+import { create } from "./utils";
+
+export function createLicense(license: LicenseObject) {
+  if (!license) return "";
+  const { name, url } = license;
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "License",
+      }),
+      create("a", {
+        href: url,
+        children: name,
+      }),
+    ],
+  });
+}

package/src/markdown/createTermsOfService.ts

@@ -0,0 +1,30 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { create } from "./utils";
+
+export function createTermsOfService(termsOfService: string | undefined) {
+  if (!createTermsOfService) return "";
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "Terms of Service",
+      }),
+      create("a", {
+        href: `${termsOfService}`,
+        children: termsOfService,
+      }),
+    ],
+  });
+}

package/src/markdown/index.ts

@@ -7,12 +7,16 @@
 
 import { escape } from "lodash";
 
+import { ContactObject, LicenseObject } from "../openapi/types";
 import { ApiPageMetadata, InfoPageMetadata } from "../types";
+import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
+import { createLicense } from "./createLicense";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
+import { createTermsOfService } from "./createTermsOfService";
 import { createVersionBadge } from "./createVersionBadge";
 import { render } from "./utils";
 
@@ -45,11 +49,14 @@ export function createApiPageMD({
 }
 
 export function createInfoPageMD({
-  info: { title, version, description },
+  info: { title, version, description, contact, license, termsOfService },
 }: InfoPageMetadata) {
   return render([
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
     createDescription(description),
+    createContactInfo(contact as ContactObject),
+    createTermsOfService(termsOfService),
+    createLicense(license as LicenseObject),
   ]);
 }

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;
@@ -400,6 +401,8 @@ export interface HttpSecuritySchemeObject {
   description?: string;
   scheme: string;
   bearerFormat?: string;
+  name?: string;
+  in?: string;
 }
 
 export interface Oauth2SecuritySchemeObject {

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;

package/lib/markdown/createFullWidthTable.d.ts

@@ -1,2 +0,0 @@
-import { Props } from "./utils";
-export declare function createFullWidthTable({ children, style, ...rest }: Props): string;

package/lib/markdown/createFullWidthTable.js

@@ -1,18 +0,0 @@
-"use strict";
-/* ============================================================================
- * Copyright (c) Palo Alto Networks
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFullWidthTable = void 0;
-const utils_1 = require("./utils");
-function createFullWidthTable({ children, style, ...rest }) {
-    return (0, utils_1.create)("table", {
-        style: { display: "table", width: "100%", ...style },
-        ...rest,
-        children,
-    });
-}
-exports.createFullWidthTable = createFullWidthTable;

package/lib/markdown/createParamsTable.d.ts

@@ -1,7 +0,0 @@
-import { ApiItem } from "../types";
-interface Props {
-    parameters: ApiItem["parameters"];
-    type: "path" | "query" | "header" | "cookie";
-}
-export declare function createParamsTable({ parameters, type }: Props): string | undefined;
-export {};

package/lib/markdown/createParamsTable.js

@@ -1,80 +0,0 @@
-"use strict";
-/* ============================================================================
- * Copyright (c) Palo Alto Networks
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createParamsTable = void 0;
-const lodash_1 = require("lodash");
-const createDescription_1 = require("./createDescription");
-const createFullWidthTable_1 = require("./createFullWidthTable");
-const schema_1 = require("./schema");
-const utils_1 = require("./utils");
-function createParamsTable({ parameters, type }) {
-    if (parameters === undefined) {
-        return undefined;
-    }
-    const params = parameters.filter((param) => (param === null || param === void 0 ? void 0 : param.in) === type);
-    if (params.length === 0) {
-        return undefined;
-    }
-    return (0, createFullWidthTable_1.createFullWidthTable)({
-        children: [
-            (0, utils_1.create)("thead", {
-                children: (0, utils_1.create)("tr", {
-                    children: (0, utils_1.create)("th", {
-                        style: { textAlign: "left" },
-                        children: `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`,
-                    }),
-                }),
-            }),
-            (0, utils_1.create)("tbody", {
-                children: params.map((param) => (0, utils_1.create)("tr", {
-                    children: (0, utils_1.create)("td", {
-                        children: [
-                            (0, utils_1.create)("code", { children: param.name }),
-                            (0, utils_1.guard)(param.schema, (schema) => (0, utils_1.create)("span", {
-                                style: { opacity: "0.6" },
-                                children: ` ${(0, schema_1.getSchemaName)(schema)}`,
-                            })),
-                            (0, utils_1.guard)(param.required, () => [
-                                (0, utils_1.create)("span", {
-                                    style: { opacity: "0.6" },
-                                    children: " — ",
-                                }),
-                                (0, utils_1.create)("strong", {
-                                    style: {
-                                        fontSize: "var(--ifm-code-font-size)",
-                                        color: "var(--openapi-required)",
-                                    },
-                                    children: " REQUIRED",
-                                }),
-                            ]),
-                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(param.schema), (message) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: (0, createDescription_1.createDescription)(message),
-                            })),
-                            (0, utils_1.guard)(param.description, (description) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: (0, createDescription_1.createDescription)(description),
-                            })),
-                            (0, utils_1.guard)(param.example, (example) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: (0, lodash_1.escape)(`Example: ${example}`),
-                            })),
-                            (0, utils_1.guard)(param.examples, (examples) => (0, utils_1.create)("div", {
-                                style: { marginTop: "var(--ifm-table-cell-padding)" },
-                                children: Object.entries(examples).map(([k, v]) => (0, utils_1.create)("div", {
-                                    children: (0, lodash_1.escape)(`Example (${k}): ${v.value}`),
-                                })),
-                            })),
-                        ],
-                    }),
-                })),
-            }),
-        ],
-    });
-}
-exports.createParamsTable = createParamsTable;

package/lib/markdown/createRequestBodyTable.d.ts

@@ -1,6 +0,0 @@
-interface Props {
-    title: string;
-    body: any;
-}
-export declare function createRequestBodyTable({ title, body }: Props): string | undefined;
-export {};

package/lib/markdown/createRequestBodyTable.js

@@ -1,14 +0,0 @@
-"use strict";
-/* ============================================================================
- * Copyright (c) Palo Alto Networks
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRequestBodyTable = void 0;
-const createSchemaTable_1 = require("./createSchemaTable");
-function createRequestBodyTable({ title, body }) {
-    return (0, createSchemaTable_1.createSchemaTable)({ title, body });
-}
-exports.createRequestBodyTable = createRequestBodyTable;