docusaurus-plugin-openapi-docs 0.0.0-1000

package/src/openapi-to-postmanv2.d.ts

@@ -0,0 +1,10 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+declare module "openapi-to-postmanv2" {
+  export default any;
+}

package/src/options.ts

@@ -0,0 +1,77 @@
+/* ============================================================================
+ * 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 { Joi } from "@docusaurus/utils-validation";
+
+const sidebarGenerators = Joi.object({
+  createDocItem: Joi.function(),
+});
+
+const sidebarOptions = Joi.object({
+  groupPathsBy: Joi.string().valid("tag", "tagGroup"),
+  categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
+  customProps: Joi.object(),
+  sidebarCollapsible: Joi.boolean(),
+  sidebarCollapsed: Joi.boolean(),
+  sidebarGenerators: sidebarGenerators,
+});
+
+const markdownGenerators = Joi.object({
+  createApiPageMD: Joi.function(),
+  createInfoPageMD: Joi.function(),
+  createTagPageMD: Joi.function(),
+  createSchemaPageMD: Joi.function(),
+});
+
+export const OptionsSchema = Joi.object({
+  id: Joi.string().required(),
+  docsPlugin: Joi.string(),
+  docsPluginId: Joi.string().required(),
+  config: Joi.object()
+    .pattern(
+      /^/,
+      Joi.object({
+        specPath: Joi.string().required(),
+        proxy: Joi.string(),
+        outputDir: Joi.string().required(),
+        template: Joi.string(),
+        infoTemplate: Joi.string(),
+        tagTemplate: Joi.string(),
+        schemaTemplate: Joi.string(),
+        downloadUrl: Joi.string(),
+        hideSendButton: Joi.boolean(),
+        showExtensions: Joi.boolean(),
+        sidebarOptions: sidebarOptions,
+        markdownGenerators: markdownGenerators,
+        showSchemas: Joi.boolean(),
+        disableCompression: Joi.boolean(),
+        version: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        label: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        baseUrl: Joi.string().when("versions", {
+          is: Joi.exist(),
+          then: Joi.required(),
+        }),
+        versions: Joi.object().pattern(
+          /^/,
+          Joi.object({
+            specPath: Joi.string().required(),
+            outputDir: Joi.string().required(),
+            label: Joi.string().required(),
+            baseUrl: Joi.string().required(),
+            downloadUrl: Joi.string(),
+          })
+        ),
+      })
+    )
+    .required(),
+});

package/src/plugin-content-docs-types.d.ts

@@ -0,0 +1,42 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+declare module "@docusaurus/plugin-content-docs-types" {
+  // Makes all properties visible when hovering over the type
+  type Expand<T extends Record<string, unknown>> = { [P in keyof T]: T[P] };
+
+  export type SidebarItemBase = {
+    className?: string;
+    customProps?: Record<string, unknown>;
+  };
+
+  export type SidebarItemLink = SidebarItemBase & {
+    type: "link";
+    href: string;
+    label: string;
+    docId: string;
+  };
+
+  type SidebarItemCategoryBase = SidebarItemBase & {
+    type: "category";
+    label: string;
+    collapsed: boolean;
+    collapsible: boolean;
+  };
+
+  export type PropSidebarItemCategory = Expand<
+    SidebarItemCategoryBase & {
+      items: PropSidebarItem[];
+    }
+  >;
+
+  export type PropSidebarItem = SidebarItemLink | PropSidebarItemCategory;
+  export type PropSidebar = PropSidebarItem[];
+  export type PropSidebars = {
+    [sidebarId: string]: PropSidebar;
+  };
+}

package/src/plugin-openapi.d.ts

@@ -0,0 +1,87 @@
+/* ============================================================================
+ * 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 type { FrontMatter as DocsFrontMatter } from "@docusaurus/types";
+import type { Props as DocsProps } from "@docusaurus/types";
+
+// TODO: figure out how to import this
+declare module "docusaurus-plugin-openapi-docs" {
+  import type { PropSidebars } from "@docusaurus/plugin-content-docs-types";
+
+  export type Options = Partial<import("./types").APIOptions>;
+
+  export type PropApiMetadata = {
+    // TODO: adjust this to our needs
+    pluginId: string;
+    version: string;
+    label: string;
+    banner: VersionBanner | null;
+    badge: boolean;
+    className: string;
+    isLast: boolean;
+    apiSidebars: PropSidebars;
+  };
+}
+
+declare module "@theme/ApiPage" {
+  import type { ApiRoute } from "@theme/ApiItem";
+  import type { PropApiMetadata } from "docusaurus-plugin-openapi";
+
+  export interface Props {
+    readonly location: { readonly pathname: string };
+    readonly apiMetadata: PropApiMetadata;
+    readonly route: {
+      readonly path: string;
+      readonly component: () => JSX.Element;
+      readonly routes: ApiRoute[];
+    };
+  }
+
+  const ApiPage: (props: Props) => JSX.Element;
+  export default ApiPage;
+}
+
+declare module "@theme/ApiItem" {
+  import type { Request } from "postman-collection";
+
+  import type { ApiItem } from "./types";
+
+  export type ApiRoute = {
+    readonly component: () => JSX.Element;
+    readonly exact: boolean;
+    readonly path: string;
+    readonly sidebar?: string;
+  };
+
+  export interface FrontMatter extends DocsFrontMatter {
+    readonly api?: object;
+  }
+
+  export type Metadata = {
+    readonly description?: string;
+    readonly title?: string;
+    readonly permalink?: string;
+    readonly previous?: { readonly permalink: string; readonly title: string };
+    readonly next?: { readonly permalink: string; readonly title: string };
+    readonly api?: ApiItem & { postman: Request }; // TODO
+    readonly type?: string;
+  };
+
+  export interface Props extends DocsProps {
+    readonly route: ApiRoute;
+    readonly content: {
+      readonly frontMatter: FrontMatter;
+      readonly metadata: Metadata;
+      readonly contentTitle: string | undefined;
+      readonly toc: array | undefined;
+      (): JSX.Element;
+    };
+  }
+
+  const ApiItem: (props: Props) => JSX.Element;
+  export default ApiItem;
+}

package/src/postman-collection.d.ts

@@ -0,0 +1,10 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+declare module "postman-collection" {
+  export default any;
+}

package/src/sidebars/index.ts

@@ -0,0 +1,322 @@
+/* ============================================================================
+ * 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 path from "path";
+
+import { ProcessedSidebarItem } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
+import {
+  ProcessedSidebar,
+  SidebarItemCategory,
+  SidebarItemCategoryLinkConfig,
+} from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import { posixPath } from "@docusaurus/utils";
+import clsx from "clsx";
+import { kebabCase } from "lodash";
+import uniq from "lodash/uniq";
+
+import { TagGroupObject, TagObject } from "../openapi/types";
+import type {
+  SidebarOptions,
+  APIOptions,
+  ApiPageMetadata,
+  ApiMetadata,
+  InfoPageMetadata,
+  SchemaPageMetadata,
+  ApiDocItemGenerator,
+} from "../types";
+
+function isApiItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "api";
+}
+
+function isInfoItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "info";
+}
+
+function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "schema";
+}
+
+const createDocItem: ApiDocItemGenerator = (
+  item,
+  { sidebarOptions: { customProps }, basePath }
+) => {
+  const sidebar_label = item.frontMatter.sidebar_label;
+  const title = item.title;
+  const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+  const className =
+    item.type === "api"
+      ? clsx(
+          {
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+          },
+          item.api.method
+        )
+      : clsx(
+          {
+            "menu__list-item--deprecated": item.schema.deprecated,
+          },
+          "schema"
+        );
+  return {
+    type: "doc" as const,
+    id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+    label: (sidebar_label as string) ?? title ?? id,
+    customProps: customProps,
+    className: className ? className : undefined,
+  };
+};
+
+function groupByTags(
+  items: ApiMetadata[],
+  sidebarOptions: SidebarOptions,
+  options: APIOptions,
+  tags: TagObject[][],
+  docPath: string
+): ProcessedSidebar {
+  let { outputDir, label, showSchemas } = options;
+
+  // Remove trailing slash before proceeding
+  outputDir = outputDir.replace(/\/$/, "");
+
+  const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } =
+    sidebarOptions;
+
+  const apiItems = items.filter(isApiItem) as ApiPageMetadata[];
+  const infoItems = items.filter(isInfoItem) as InfoPageMetadata[];
+  const schemaItems = items.filter(isSchemaItem) as SchemaPageMetadata[];
+  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 operationTags = uniq(
+    apiItems
+      .flatMap((item) => item.api.tags)
+      .filter((item): item is string => !!item)
+  );
+  const schemaTags = uniq(
+    schemaItems
+      .flatMap((item) => item.schema["x-tags"])
+      .filter((item): item is string => !!item)
+  );
+
+  // Combine globally defined tags with operation and schema tags
+  // Only include global tag if referenced in operation/schema tags
+  let apiTags: string[] = [];
+  tags.flat().forEach((tag) => {
+    // Should we also check x-displayName?
+    if (operationTags.includes(tag.name!) || schemaTags.includes(tag.name!)) {
+      apiTags.push(tag.name!);
+    }
+  });
+
+  if (sidebarOptions.groupPathsBy !== "tagGroup") {
+    apiTags = uniq(apiTags.concat(operationTags, schemaTags));
+  }
+
+  const basePath = docPath
+    ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
+    : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
+
+  const createDocItemFnContext = {
+    sidebarOptions,
+    basePath,
+  };
+  const createDocItemFn =
+    sidebarOptions.sidebarGenerators?.createDocItem ?? createDocItem;
+
+  let rootIntroDoc = undefined;
+  if (infoItems.length === 1) {
+    const infoItem = infoItems[0];
+    const id = infoItem.id;
+    rootIntroDoc = {
+      type: "doc" as const,
+      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+    };
+  }
+
+  const tagged = apiTags
+    .map((tag) => {
+      // Map info object to tag
+      const taggedInfoObject = intros.find((i) =>
+        i.tags ? i.tags.find((t: any) => t.name === tag) : undefined
+      );
+      const tagObject = tags.flat().find(
+        (t) =>
+          tag === t.name && {
+            name: tag,
+            description: `${tag} Index`,
+          }
+      );
+
+      // TODO: perhaps move this into a getLinkConfig() function
+      // Default to no link config (spindowns only)
+      let linkConfig = undefined;
+      if (taggedInfoObject !== undefined && categoryLinkSource === "info") {
+        linkConfig = {
+          type: "doc",
+          id:
+            basePath === "" || undefined
+              ? `${taggedInfoObject.id}`
+              : `${basePath}/${taggedInfoObject.id}`,
+        } as SidebarItemCategoryLinkConfig;
+      }
+
+      // TODO: perhaps move this into a getLinkConfig() function
+      if (tagObject !== undefined && categoryLinkSource === "tag") {
+        const tagId = kebabCase(tagObject.name);
+        linkConfig = {
+          type: "doc",
+          id:
+            basePath === "" || undefined ? `${tagId}` : `${basePath}/${tagId}`,
+        } as SidebarItemCategoryLinkConfig;
+      }
+
+      if (categoryLinkSource === "auto") {
+        linkConfig = {
+          type: "generated-index" as "generated-index",
+          title: tag,
+          slug: label
+            ? posixPath(
+                path.join(
+                  "/category",
+                  basePath,
+                  kebabCase(label),
+                  kebabCase(tag)
+                )
+              )
+            : posixPath(path.join("/category", basePath, kebabCase(tag))),
+        } as SidebarItemCategoryLinkConfig;
+      }
+
+      const taggedApiItems = apiItems.filter(
+        (item) => !!item.api.tags?.includes(tag)
+      );
+      const taggedSchemaItems = schemaItems.filter(
+        (item) => !!item.schema["x-tags"]?.includes(tag)
+      );
+
+      return {
+        type: "category" as const,
+        label: tagObject?.["x-displayName"] ?? tag,
+        link: linkConfig,
+        collapsible: sidebarCollapsible,
+        collapsed: sidebarCollapsed,
+        items: [...taggedSchemaItems, ...taggedApiItems].map((item) =>
+          createDocItemFn(item, createDocItemFnContext)
+        ),
+      };
+    })
+    .filter((item) => item.items.length > 0); // Filter out any categories with no items.
+
+  // Handle items with no tag
+  const untaggedItems = apiItems
+    .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+    .map((item) => createDocItemFn(item, createDocItemFnContext));
+  let untagged: SidebarItemCategory[] = [];
+  if (untaggedItems.length > 0) {
+    untagged = [
+      {
+        type: "category" as const,
+        label: "UNTAGGED",
+        collapsible: sidebarCollapsible!,
+        collapsed: sidebarCollapsed!,
+        items: apiItems
+          .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
+      },
+    ];
+  }
+
+  let schemas: SidebarItemCategory[] = [];
+  if (showSchemas && schemaItems.length > 0) {
+    schemas = [
+      {
+        type: "category" as const,
+        label: "Schemas",
+        collapsible: sidebarCollapsible!,
+        collapsed: sidebarCollapsed!,
+        items: schemaItems
+          .filter(({ schema }) => !schema["x-tags"])
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
+      },
+    ];
+  }
+
+  // Shift root intro doc to top of sidebar
+  // TODO: Add input validation for categoryLinkSource options
+  if (rootIntroDoc && categoryLinkSource !== "info") {
+    tagged.unshift(rootIntroDoc as any);
+  }
+
+  return [...tagged, ...untagged, ...schemas];
+}
+
+export default function generateSidebarSlice(
+  sidebarOptions: SidebarOptions,
+  options: APIOptions,
+  api: ApiMetadata[],
+  tags: TagObject[][],
+  docPath: string,
+  tagGroups?: TagGroupObject[]
+) {
+  let sidebarSlice: ProcessedSidebar = [];
+
+  if (sidebarOptions.groupPathsBy === "tagGroup") {
+    let schemasGroup: ProcessedSidebar = [];
+    tagGroups?.forEach((tagGroup) => {
+      //filter tags only included in group
+      const filteredTags: TagObject[] = [];
+      tags[0].forEach((tag) => {
+        if (tagGroup.tags.includes(tag.name as string)) {
+          filteredTags.push(tag);
+        }
+      });
+
+      const groupCategory = {
+        type: "category" as const,
+        label: tagGroup.name,
+        collapsible: true,
+        collapsed: true,
+        items: groupByTags(
+          api,
+          sidebarOptions,
+          options,
+          [filteredTags],
+          docPath
+        ),
+      };
+
+      if (options.showSchemas) {
+        // For the first tagGroup, save the generated "Schemas" category for later.
+        if (schemasGroup.length === 0) {
+          schemasGroup = groupCategory.items?.filter(
+            (item) => item.type === "category" && item.label === "Schemas"
+          );
+        }
+        // Remove the "Schemas" category from every `groupCategory`.
+        groupCategory.items = groupCategory.items.filter((item) =>
+          "label" in item ? item.label !== "Schemas" : true
+        );
+      }
+      sidebarSlice.push(groupCategory as ProcessedSidebarItem);
+    });
+    // Add `schemasGroup` to the end of the sidebar.
+    sidebarSlice.push(...schemasGroup);
+  } else if (sidebarOptions.groupPathsBy === "tag") {
+    sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
+  }
+
+  return sidebarSlice;
+}

package/src/sidebars/utils.ts

@@ -0,0 +1,29 @@
+/* ============================================================================
+ * 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 { render } from "mustache";
+
+export function versionSelector(versions: object[]) {
+  const template = `<div class="dropdown dropdown--hoverable dropdown--right">
+  <button class="button button--block button--sm button--secondary"><span>Select API Version</span></button>
+  <ul class="dropdown__menu">
+    {{#.}}<li><a class="dropdown__link" href="{{{baseUrl}}}">{{{label}}}</a></li>{{/.}}
+  </ul>
+</div>
+      `;
+  const view = render(template, versions);
+  return view;
+}
+
+export function versionCrumb(version: string) {
+  const template = `<ul style="display: flex;" class="breadcrumbs breadcrumbs--sm">
+  <li style="margin-left: auto; margin-right: 0;" class="breadcrumbs__item breadcrumbs__item--active">
+  <a class="breadcrumbs__link"><span>{{{.}}}</span></a></li></ul>
+      `;
+  const view = render(template, version);
+  return view;
+}