docusaurus-plugin-openapi-docs 1.0.0 → 1.0.3

package/src/openapi/utils/types.ts

@@ -0,0 +1,303 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+
+export interface OpenAPISpec {
+  openapi: string;
+  info: OpenAPIInfo;
+  servers?: OpenAPIServer[];
+  paths: OpenAPIPaths;
+  components?: OpenAPIComponents;
+  security?: OpenAPISecurityRequirement[];
+  tags?: OpenAPITag[];
+  externalDocs?: OpenAPIExternalDocumentation;
+  "x-webhooks"?: OpenAPIPaths;
+  webhooks?: OpenAPIPaths;
+}
+
+export interface OpenAPIInfo {
+  title: string;
+  version: string;
+
+  description?: string;
+  summary?: string;
+  termsOfService?: string;
+  contact?: OpenAPIContact;
+  license?: OpenAPILicense;
+}
+
+export interface OpenAPIServer {
+  url: string;
+  description?: string;
+  variables?: { [name: string]: OpenAPIServerVariable };
+}
+
+export interface OpenAPIServerVariable {
+  enum?: string[];
+  default: string;
+  description?: string;
+}
+
+export interface OpenAPIPaths {
+  [path: string]: OpenAPIPath;
+}
+export interface OpenAPIRef {
+  $ref: string;
+}
+
+export type Referenced<T> = OpenAPIRef | T;
+
+export interface OpenAPIPath {
+  summary?: string;
+  description?: string;
+  get?: OpenAPIOperation;
+  put?: OpenAPIOperation;
+  post?: OpenAPIOperation;
+  delete?: OpenAPIOperation;
+  options?: OpenAPIOperation;
+  head?: OpenAPIOperation;
+  patch?: OpenAPIOperation;
+  trace?: OpenAPIOperation;
+  servers?: OpenAPIServer[];
+  parameters?: Array<Referenced<OpenAPIParameter>>;
+  $ref?: string;
+}
+
+export interface OpenAPIXCodeSample {
+  lang: string;
+  label?: string;
+  source: string;
+}
+
+export interface OpenAPIOperation {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: OpenAPIExternalDocumentation;
+  operationId?: string;
+  parameters?: Array<Referenced<OpenAPIParameter>>;
+  requestBody?: Referenced<OpenAPIRequestBody>;
+  responses: OpenAPIResponses;
+  callbacks?: { [name: string]: Referenced<OpenAPICallback> };
+  deprecated?: boolean;
+  security?: OpenAPISecurityRequirement[];
+  servers?: OpenAPIServer[];
+  "x-codeSamples"?: OpenAPIXCodeSample[];
+  "x-code-samples"?: OpenAPIXCodeSample[]; // deprecated
+}
+
+export interface OpenAPIParameter {
+  name: string;
+  in?: OpenAPIParameterLocation;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  style?: OpenAPIParameterStyle;
+  explode?: boolean;
+  allowReserved?: boolean;
+  schema?: Referenced<OpenAPISchema>;
+  example?: any;
+  examples?: { [media: string]: Referenced<OpenAPIExample> };
+  content?: { [media: string]: OpenAPIMediaType };
+  encoding?: Record<string, OpenAPIEncoding>;
+  const?: any;
+}
+
+export interface OpenAPIExample {
+  value: any;
+  summary?: string;
+  description?: string;
+  externalValue?: string;
+}
+
+export interface OpenAPISchema {
+  $ref?: string;
+  type?: string | string[];
+  properties?: { [name: string]: OpenAPISchema };
+  patternProperties?: { [name: string]: OpenAPISchema };
+  additionalProperties?: boolean | OpenAPISchema;
+  unevaluatedProperties?: boolean | OpenAPISchema;
+  description?: string;
+  default?: any;
+  items?: OpenAPISchema | OpenAPISchema[] | boolean;
+  required?: string[];
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  deprecated?: boolean;
+  format?: string;
+  externalDocs?: OpenAPIExternalDocumentation;
+  discriminator?: OpenAPIDiscriminator;
+  nullable?: boolean;
+  oneOf?: OpenAPISchema[];
+  anyOf?: OpenAPISchema[];
+  allOf?: OpenAPISchema[];
+  not?: OpenAPISchema;
+
+  title?: string;
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: boolean | number;
+  minimum?: number;
+  exclusiveMinimum?: boolean | number;
+  maxLength?: number;
+  minLength?: number;
+  pattern?: string;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  maxProperties?: number;
+  minProperties?: number;
+  enum?: any[];
+  example?: any;
+
+  if?: OpenAPISchema;
+  else?: OpenAPISchema;
+  then?: OpenAPISchema;
+  examples?: any[];
+  const?: string;
+  contentEncoding?: string;
+  contentMediaType?: string;
+  prefixItems?: OpenAPISchema[];
+  additionalItems?: OpenAPISchema | boolean;
+}
+
+export interface OpenAPIDiscriminator {
+  propertyName: string;
+  mapping?: { [name: string]: string };
+  "x-explicitMappingOnly"?: boolean;
+}
+
+export interface OpenAPIMediaType {
+  schema?: Referenced<OpenAPISchema>;
+  example?: any;
+  examples?: { [name: string]: Referenced<OpenAPIExample> };
+  encoding?: { [field: string]: OpenAPIEncoding };
+}
+
+export interface OpenAPIEncoding {
+  contentType: string;
+  headers?: { [name: string]: Referenced<OpenAPIHeader> };
+  style: OpenAPIParameterStyle;
+  explode: boolean;
+  allowReserved: boolean;
+}
+
+export type OpenAPIParameterLocation = "query" | "header" | "path" | "cookie";
+export type OpenAPIParameterStyle =
+  | "matrix"
+  | "label"
+  | "form"
+  | "simple"
+  | "spaceDelimited"
+  | "pipeDelimited"
+  | "deepObject";
+
+export interface OpenAPIRequestBody {
+  description?: string;
+  required?: boolean;
+  content: { [mime: string]: OpenAPIMediaType };
+
+  "x-examples"?: {
+    [mime: string]: { [name: string]: Referenced<OpenAPIExample> };
+  };
+  "x-example"?: { [mime: string]: any };
+}
+
+export interface OpenAPIResponses {
+  [code: string]: Referenced<OpenAPIResponse>;
+}
+
+export interface OpenAPIResponse
+  extends Pick<OpenAPIRequestBody, "description" | "x-examples" | "x-example"> {
+  headers?: { [name: string]: Referenced<OpenAPIHeader> };
+  links?: { [name: string]: Referenced<OpenAPILink> };
+  content?: { [mime: string]: OpenAPIMediaType };
+}
+
+export interface OpenAPILink {
+  $ref?: string;
+}
+
+export type OpenAPIHeader = Omit<OpenAPIParameter, "in" | "name">;
+
+export interface OpenAPICallback {
+  [name: string]: OpenAPIPath;
+}
+
+export interface OpenAPIComponents {
+  schemas?: { [name: string]: Referenced<OpenAPISchema> };
+  responses?: { [name: string]: Referenced<OpenAPIResponse> };
+  parameters?: { [name: string]: Referenced<OpenAPIParameter> };
+  examples?: { [name: string]: Referenced<OpenAPIExample> };
+  requestBodies?: { [name: string]: Referenced<OpenAPIRequestBody> };
+  headers?: { [name: string]: Referenced<OpenAPIHeader> };
+  securitySchemes?: { [name: string]: Referenced<OpenAPISecurityScheme> };
+  links?: { [name: string]: Referenced<OpenAPILink> };
+  callbacks?: { [name: string]: Referenced<OpenAPICallback> };
+}
+
+export interface OpenAPISecurityRequirement {
+  [name: string]: string[];
+}
+
+export interface OpenAPISecurityScheme {
+  type: "apiKey" | "http" | "oauth2" | "openIdConnect";
+  description?: string;
+  name?: string;
+  in?: "query" | "header" | "cookie";
+  scheme?: string;
+  bearerFormat: string;
+  flows: {
+    implicit?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      authorizationUrl: string;
+    };
+    password?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      tokenUrl: string;
+    };
+    clientCredentials?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      tokenUrl: string;
+    };
+    authorizationCode?: {
+      refreshUrl?: string;
+      scopes: Record<string, string>;
+      tokenUrl: string;
+    };
+  };
+  openIdConnectUrl?: string;
+}
+
+export interface OpenAPITag {
+  name: string;
+  description?: string;
+  externalDocs?: OpenAPIExternalDocumentation;
+  "x-displayName"?: string;
+}
+
+export interface OpenAPIExternalDocumentation {
+  description?: string;
+  url: string;
+}
+
+export interface OpenAPIContact {
+  name?: string;
+  url?: string;
+  email?: string;
+}
+
+export interface OpenAPILicense {
+  name: string;
+  url?: string;
+  identifier?: string;
+}

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,15 @@
 
 import {
   ProcessedSidebar,
+  SidebarItemCategory,
+  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 +27,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 +87,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 taggedInfoObject = intros.find((i) =>
+        i.tags ? i.tags.includes(tag) : undefined
+      );
+      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 (taggedInfoObject !== undefined && categoryLinkSource === "info") {
+        linkConfig = {
+          type: "doc",
+          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}/${tagId}`,
+        } 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 +151,47 @@ function groupByTags(
     })
     .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];
+  // Handle items with no tag
+  const untaggedItems = apiItems
+    .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+    .map(createDocItem);
+  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(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, ...untagged];
 }
 
 export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  api: ApiMetadata[]
+  api: ApiMetadata[],
+  tags: TagObject[]
 ) {
   let sidebarSlice: ProcessedSidebar = [];
-  if (sidebarOptions.groupPathsBy === "tags") {
+  if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,
-      options
+      options,
+      tags
     );
   }
   return sidebarSlice;

package/src/types.ts

@@ -5,13 +5,13 @@
  * 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,
   OperationObject,
   SecuritySchemeObject,
+  TagObject,
 } from "./openapi/types";
 
 export type {
@@ -39,7 +39,7 @@ export interface LoadedContent {
   // loadedDocs: DocPageMetadata[]; TODO: cleanup
 }
 
-export type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
 
 export interface ApiMetadataBase {
   sidebar?: string;
@@ -48,6 +48,8 @@ export interface ApiMetadataBase {
   //
   id: string; // TODO legacy versioned id => try to remove
   unversionedId: string; // TODO new unversioned id => try to rename to "id"
+  infoId?: string;
+  infoPath?: string;
   title: string;
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
@@ -80,6 +82,15 @@ export interface InfoPageMetadata extends ApiMetadataBase {
   type: "info";
   info: ApiInfo;
   markdown?: string;
+  securitySchemes?: {
+    [key: string]: SecuritySchemeObject;
+  };
+}
+
+export interface TagPageMetadata extends ApiMetadataBase {
+  type: "tag";
+  tag: TagObject;
+  markdown?: string;
 }
 
 export type ApiInfo = InfoObject;
@@ -91,6 +102,7 @@ export interface ApiNavLink {
 
 export interface SidebarOptions {
   groupPathsBy?: string;
+  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 {};