docusaurus-plugin-openapi-docs 1.0.1 → 1.0.4

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/options.ts

@@ -7,14 +7,47 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
-import type { PluginOptions } from "./types";
-
-export const DEFAULT_OPTIONS: PluginOptions = {
-  id: "default",
-  config: {},
-};
+const sidebarOptions = Joi.object({
+  groupPathsBy: Joi.string().valid("tag"),
+  categoryLinkSource: Joi.string().valid("tag", "info"),
+  customProps: Joi.object(),
+  sidebarCollapsible: Joi.boolean(),
+  sidebarCollapsed: Joi.boolean(),
+});
 
 export const OptionsSchema = Joi.object({
-  id: Joi.string().default(DEFAULT_OPTIONS.id),
-  config: Joi.object().default(DEFAULT_OPTIONS.config),
+  id: Joi.string().required(),
+  docPluginId: Joi.string().required(),
+  config: Joi.object()
+    .pattern(
+      /^/,
+      Joi.object({
+        specPath: Joi.string().required(),
+        outputDir: Joi.string().required(),
+        template: Joi.string(),
+        sidebarOptions: sidebarOptions,
+        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(),
+          })
+        ),
+      })
+    )
+    .required(),
 });

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,37 +27,46 @@ 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[],
+  docPath: string
 ): 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)
   );
 
-  // TODO: optimize this or make it a function
-  const basePath = outputDir
-    .slice(outputDir.indexOf("/", 1))
-    .replace(/^\/+/g, "");
+  const basePath = docPath
+    ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
+    : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
 
   function createDocItem(item: ApiPageMetadata): SidebarItemDoc {
     const sidebar_label = item.frontMatter.sidebar_label;
@@ -61,7 +74,8 @@ function groupByTags(
     const id = item.id;
     return {
       type: "doc" as const,
-      id: `${basePath}/${item.id}`,
+      id:
+        basePath === "" || undefined ? `${item.id}` : `${basePath}/${item.id}`,
       label: (sidebar_label as string) ?? title ?? id,
       customProps: customProps,
       className: clsx(
@@ -74,11 +88,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 +152,49 @@ 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[],
+  docPath: string
 ) {
   let sidebarSlice: ProcessedSidebar = [];
-  if (sidebarOptions.groupPathsBy === "tags") {
+  if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,
-      options
+      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;
+}