docusaurus-plugin-openapi-docs 1.0.1 → 1.0.2

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { Request } from "@paloaltonetworks/postman-collection";
+import type Request from "@paloaltonetworks/postman-collection";
 import { InfoObject, OperationObject, SecuritySchemeObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
@@ -60,6 +60,7 @@ export interface ApiNavLink {
 }
 export interface SidebarOptions {
     groupPathsBy?: string;
+    categoryLinkSource?: string;
     customProps?: {
         [key: string]: unknown;
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -33,7 +33,6 @@
     "@types/fs-extra": "^9.0.13",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
-    "@types/postman-collection": "^3.5.7",
     "utility-types": "^3.10.0"
   },
   "dependencies": {
@@ -61,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "27f594d26440ffe6f890b35c79847e065a96723e"
+  "gitHead": "526f2d10bc187bc7095ac70d5b1453b9b92c114f"
 }

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?.categoryLinkSource === "info" // Only use utils template if set to "info"
+                ? 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,52 @@
+/* ============================================================================
+ * 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, guard } from "./utils";
+
+export function createContactInfo(contact: ContactObject) {
+  if (!contact || !Object.keys(contact).length) 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: [
+          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

@@ -0,0 +1,34 @@
+/* ============================================================================
+ * 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, guard } from "./utils";
+
+export function createLicense(license: LicenseObject) {
+  if (!license || !Object.keys(license).length) return "";
+  const { name, url } = license;
+
+  return create("div", {
+    style: {
+      marginBottom: "var(--ifm-paragraph-margin-bottom)",
+    },
+    children: [
+      create("h3", {
+        style: {
+          marginBottom: "0.25rem",
+        },
+        children: "License",
+      }),
+      guard(url, () =>
+        create("a", {
+          href: url,
+          children: name ?? url,
+        })
+      ),
+    ],
+  });
+}

package/src/markdown/createSchemaDetails.ts

@@ -242,7 +242,12 @@ interface Props {
 }
 
 export function createSchemaDetails({ title, body, ...rest }: Props) {
-  if (body === undefined || body.content === undefined) {
+  if (
+    body === undefined ||
+    body.content === undefined ||
+    Object.keys(body).length === 0 ||
+    Object.keys(body.content).length === 0
+  ) {
     return undefined;
   }
 
@@ -250,7 +255,6 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
   // NOTE: We just pick a random content-type.
   // How common is it to have multiple?
   const randomFirstKey = Object.keys(body.content)[0];
-
   const firstBody = body.content[randomFirstKey].schema;
 
   if (firstBody === undefined) {

package/src/markdown/createStatusCodes.ts

@@ -26,7 +26,7 @@ export function createStatusCodes({ responses }: Props) {
 
   return create("div", {
     children: [
-      create("Tabs", {
+      create("ApiTabs", {
         children: codes.map((code) => {
           return create("TabItem", {
             label: code,

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 (!termsOfService) 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";
 
@@ -30,7 +34,7 @@ export function createApiPageMD({
   return render([
     `import ParamsItem from "@theme/ParamsItem";\n`,
     `import SchemaItem from "@theme/SchemaItem"\n`,
-    `import Tabs from "@theme/Tabs";\n`,
+    `import ApiTabs from "@theme/ApiTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
@@ -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

@@ -9,8 +9,8 @@ import path from "path";
 
 import { Globby, GlobExcludeDefault } from "@docusaurus/utils";
 import Converter from "@paloaltonetworks/openapi-to-postmanv2";
-// @ts-ignore
-import sdk, { Collection } from "@paloaltonetworks/postman-collection";
+import sdk from "@paloaltonetworks/postman-collection";
+import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 import fs from "fs-extra";
 import yaml from "js-yaml";
@@ -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",
       },
     };
@@ -175,8 +179,7 @@ function bindCollectionToApiItems(
   items: ApiMetadata[],
   postmanCollection: sdk.Collection
 ) {
-  // @ts-ignore
-  postmanCollection.forEachItem((item) => {
+  postmanCollection.forEachItem((item: any) => {
     const method = item.request.method.toLowerCase();
     const path = item.request.url
       .getPath({ unresolved: true }) // unresolved returns "/:variableName" instead of "/<type>"
@@ -246,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 {
@@ -182,6 +183,7 @@ export interface ParameterObject {
   examples?: Map<ExampleObject>;
   //
   content?: Map<MediaTypeObject>;
+  param?: Object;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
 }
@@ -293,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;
@@ -399,6 +401,8 @@ export interface HttpSecuritySchemeObject {
   description?: string;
   scheme: string;
   bearerFormat?: string;
+  name?: string;
+  in?: string;
 }
 
 export interface Oauth2SecuritySchemeObject {

package/src/{markdown/createRequestBodyTable.ts → postman-collection.d.ts}

@@ -5,13 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { createSchemaTable } from "./createSchemaTable";
-
-interface Props {
-  title: string;
-  body: any;
-}
-
-export function createRequestBodyTable({ title, body }: Props) {
-  return createSchemaTable({ title, body });
+declare module "@paloaltonetworks/postman-collection" {
+  export default any;
 }

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,37 @@ 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 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 apiTags = uniq(
     apiItems
       .flatMap((item) => item.api.tags)
       .filter((item): item is string => !!item)
@@ -74,11 +86,61 @@ function groupByTags(
     };
   }
 
-  const tagged = tags
+  let rootIntroDoc = undefined;
+  if (infoItems.length === 1) {
+    const infoItem = infoItems[0];
+    const id = infoItem.id;
+    rootIntroDoc = {
+      type: "doc" as const,
+      id: `${basePath}/${id}`,
+    };
+  }
+
+  const tagged = apiTags
     .map((tag) => {
+      // Map info object to tag
+      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 this into a getLinkConfig() function
+      let linkConfig = undefined;
+      if (infoObject !== undefined && categoryLinkSource === "info") {
+        linkConfig = {
+          type: "doc",
+          id: `${basePath}/${infoObject.id}`,
+        } as SidebarItemCategoryLinkConfig;
+      }
+
+      // TODO: perhaps move this into a getLinkConfig() function
+      if (tagObject !== undefined && categoryLinkSource === "tag") {
+        const linkDescription = tagObject?.description;
+        linkConfig = {
+          type: "generated-index" as "generated-index",
+          title: tag,
+          description: linkDescription,
+          slug: "/category/" + kebabCase(tag),
+        } 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,
+        link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
         items: apiItems
@@ -88,33 +150,41 @@ 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 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];
 }
 
 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

@@ -5,8 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-// @ts-ignore
-import type { Request } from "@paloaltonetworks/postman-collection";
+import type Request from "@paloaltonetworks/postman-collection";
 
 import {
   InfoObject,
@@ -91,6 +90,7 @@ export interface ApiNavLink {
 
 export interface SidebarOptions {
   groupPathsBy?: string;
+  categoryLinkSource?: string;
   customProps?: { [key: string]: unknown };
   sidebarCollapsible?: boolean;
   sidebarCollapsed?: boolean;