docusaurus-plugin-openapi-docs 0.0.0-345

package/src/sidebars/index.ts

@@ -0,0 +1,121 @@
+/* ============================================================================
+ * 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 {
+  ProcessedSidebar,
+  SidebarItemDoc,
+} from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import clsx from "clsx";
+import uniq from "lodash/uniq";
+
+import type {
+  SidebarOptions,
+  APIOptions,
+  ApiPageMetadata,
+  ApiMetadata,
+} from "../types";
+
+function isApiItem(item: ApiMetadata): item is ApiMetadata {
+  return item.type === "api";
+}
+
+function groupByTags(
+  items: ApiPageMetadata[],
+  sidebarOptions: SidebarOptions,
+  options: APIOptions
+): 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 apiItems = items.filter(isApiItem);
+
+  // TODO: make sure we only take the first tag
+  const tags = uniq(
+    apiItems
+      .flatMap((item) => item.api.tags)
+      .filter((item): item is string => !!item)
+  );
+
+  // TODO: optimize this or make it a function
+  const basePath = outputDir
+    .slice(outputDir.indexOf("/", 1))
+    .replace(/^\/+/g, "");
+
+  function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
+    const sidebar_label = item.frontMatter.sidebar_label;
+    const title = item.title;
+    const id = item.id;
+    return {
+      type: "doc" as const,
+      id: `${basePath}/${item.id}`,
+      label: (sidebar_label as string) ?? title ?? id,
+      customProps: customProps,
+      className: clsx(
+        {
+          "menu__list-item--deprecated": item.api.deprecated,
+          "api-method": !!item.api.method,
+        },
+        item.api.method
+      ),
+    };
+  }
+
+  const tagged = tags
+    .map((tag) => {
+      return {
+        type: "category" as const,
+        label: tag,
+        collapsible: sidebarCollapsible,
+        collapsed: sidebarCollapsed,
+        items: apiItems
+          .filter((item) => !!item.api.tags?.includes(tag))
+          .map(createDocItem),
+      };
+    })
+    .filter((item) => item.items.length > 0); // Filter out any categories with no items.
+
+  // 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
+  //     items: apiItems
+  //       //@ts-ignore
+  //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+  //       .map(createDocItem),
+  //   },
+  // ];
+  return [...tagged];
+}
+
+export default function generateSidebarSlice(
+  sidebarOptions: SidebarOptions,
+  options: APIOptions,
+  api: ApiMetadata[]
+) {
+  let sidebarSlice: ProcessedSidebar = [];
+  if (sidebarOptions.groupPathsBy === "tags") {
+    sidebarSlice = groupByTags(
+      api as ApiPageMetadata[],
+      sidebarOptions,
+      options
+    );
+  }
+  return sidebarSlice;
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+/* ============================================================================
+ * 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 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 {
+  id?: string;
+  config: {
+    [key: string]: APIOptions;
+  };
+}
+
+export interface APIOptions {
+  specPath: string;
+  outputDir: string;
+  template?: string;
+  sidebarOptions?: SidebarOptions;
+}
+
+export interface LoadedContent {
+  loadedApi: ApiMetadata[];
+  // loadedDocs: DocPageMetadata[]; TODO: cleanup
+}
+
+export type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+
+export interface ApiMetadataBase {
+  sidebar?: string;
+  previous?: ApiNavLink;
+  next?: ApiNavLink;
+  //
+  id: string; // TODO legacy versioned id => try to remove
+  unversionedId: string; // TODO new unversioned id => try to rename to "id"
+  title: string;
+  description: string;
+  source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
+  sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
+  slug: string;
+  permalink: string;
+  sidebarPosition?: number;
+  frontMatter: Record<string, unknown>;
+}
+
+export interface ApiPageMetadata extends ApiMetadataBase {
+  json?: string;
+  type: "api";
+  api: ApiItem;
+  markdown?: string;
+}
+
+export interface ApiItem extends OperationObject {
+  method: string; // get, post, put, etc...
+  path: string; // The endpoint path => "/api/getPets"
+  jsonRequestBodyExample: string;
+  securitySchemes?: {
+    [key: string]: SecuritySchemeObject;
+  };
+  postman?: Request;
+  info: InfoObject;
+}
+
+export interface InfoPageMetadata extends ApiMetadataBase {
+  type: "info";
+  info: ApiInfo;
+  markdown?: string;
+}
+
+export type ApiInfo = InfoObject;
+
+export interface ApiNavLink {
+  title: string;
+  permalink: string;
+}
+
+export interface SidebarOptions {
+  groupPathsBy?: string;
+  customProps?: { [key: string]: unknown };
+  sidebarCollapsible?: boolean;
+  sidebarCollapsed?: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "lib"
+  },
+  "include": ["src"]
+}