docusaurus-plugin-openapi-docs 1.0.0

package/src/openapi/types.ts

@@ -0,0 +1,430 @@
+/* ============================================================================
+ * 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 { JSONSchema4, JSONSchema6, JSONSchema7 } from "json-schema";
+
+interface Map<T> {
+  [key: string]: T;
+}
+
+export interface OpenApiObject {
+  openapi: string;
+  info: InfoObject;
+  servers?: ServerObject[];
+  paths: PathsObject;
+  components?: ComponentsObject;
+  security?: SecurityRequirementObject[];
+  tags?: TagObject[];
+  externalDocs?: ExternalDocumentationObject;
+}
+
+export interface OpenApiObjectWithRef {
+  openapi: string;
+  info: InfoObject;
+  servers?: ServerObject[];
+  paths: PathsObjectWithRef;
+  components?: ComponentsObjectWithRef;
+  security?: SecurityRequirementObject[];
+  tags?: TagObject[];
+  externalDocs?: ExternalDocumentationObject;
+}
+
+export interface InfoObject {
+  title: string;
+  description?: string;
+  termsOfService?: string;
+  contact?: ContactObject;
+  license?: LicenseObject;
+  version: string;
+}
+
+export interface ContactObject {
+  name?: string;
+  url?: string;
+  email?: string;
+}
+
+export interface LicenseObject {
+  name: string;
+  url?: string;
+}
+
+export interface ServerObject {
+  url: string;
+  description?: string;
+  variables?: Map<ServerVariable>;
+}
+
+export interface ServerVariable {
+  enum?: string[];
+  default: string;
+  description?: string;
+}
+
+export interface ComponentsObject {
+  schemas?: Map<SchemaObject>;
+  responses?: Map<ResponseObject>;
+  parameters?: Map<ParameterObject>;
+  examples?: Map<ExampleObject>;
+  requestBodies?: Map<RequestBodyObject>;
+  headers?: Map<HeaderObject>;
+  securitySchemes?: Map<SecuritySchemeObject>;
+  links?: Map<LinkObject>;
+  callbacks?: Map<CallbackObject>;
+}
+
+export interface ComponentsObjectWithRef {
+  schemas?: Map<SchemaObjectWithRef | ReferenceObject>;
+  responses?: Map<ResponseObjectWithRef | ReferenceObject>;
+  parameters?: Map<ParameterObjectWithRef | ReferenceObject>;
+  examples?: Map<ExampleObject | ReferenceObject>;
+  requestBodies?: Map<RequestBodyObjectWithRef | ReferenceObject>;
+  headers?: Map<HeaderObjectWithRef | ReferenceObject>;
+  securitySchemes?: Map<SecuritySchemeObject | ReferenceObject>;
+  links?: Map<LinkObject | ReferenceObject>;
+  callbacks?: Map<CallbackObjectWithRef | ReferenceObject>;
+}
+
+export type PathsObject = Map<PathItemObject>;
+
+export type PathsObjectWithRef = Map<PathItemObjectWithRef>;
+
+export interface PathItemObject {
+  $ref?: string;
+  summary?: string;
+  description?: string;
+  get?: OperationObject;
+  put?: OperationObject;
+  post?: OperationObject;
+  delete?: OperationObject;
+  options?: OperationObject;
+  head?: OperationObject;
+  patch?: OperationObject;
+  trace?: OperationObject;
+  servers?: ServerObject[];
+  parameters?: ParameterObject[];
+}
+
+export interface PathItemObjectWithRef {
+  $ref?: string;
+  summary?: string;
+  description?: string;
+  get?: OperationObjectWithRef;
+  put?: OperationObjectWithRef;
+  post?: OperationObjectWithRef;
+  delete?: OperationObjectWithRef;
+  options?: OperationObjectWithRef;
+  head?: OperationObjectWithRef;
+  patch?: OperationObjectWithRef;
+  trace?: OperationObjectWithRef;
+  servers?: ServerObject[];
+  parameters?: (ParameterObjectWithRef | ReferenceObject)[];
+}
+
+export interface OperationObject {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+  operationId?: string;
+  parameters?: ParameterObject[];
+  requestBody?: RequestBodyObject;
+  responses: ResponsesObject;
+  callbacks?: Map<CallbackObject>;
+  deprecated?: boolean;
+  security?: SecurityRequirementObject[];
+  servers?: ServerObject[];
+
+  // extensions
+  "x-deprecated-description"?: string;
+}
+
+export interface OperationObjectWithRef {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+  operationId?: string;
+  parameters?: (ParameterObjectWithRef | ReferenceObject)[];
+  requestBody?: RequestBodyObjectWithRef | ReferenceObject;
+  responses: ResponsesObjectWithRef;
+  callbacks?: Map<CallbackObjectWithRef | ReferenceObject>;
+  deprecated?: boolean;
+  security?: SecurityRequirementObject[];
+  servers?: ServerObject[];
+
+  // extensions
+  "x-deprecated-description"?: string;
+}
+
+export interface ExternalDocumentationObject {
+  description?: string;
+  url: string;
+}
+
+export interface ParameterObject {
+  name: string;
+  in: "query" | "header" | "path" | "cookie";
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  //
+  style?: string;
+  explode?: string;
+  allowReserved?: boolean;
+  schema?: SchemaObject;
+  example?: any;
+  examples?: Map<ExampleObject>;
+  //
+  content?: Map<MediaTypeObject>;
+  // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+  // pipeDelimited and deepObject
+}
+
+export interface ParameterObjectWithRef {
+  name: string;
+  in: string;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  //
+  style?: string;
+  explode?: string;
+  allowReserved?: boolean;
+  schema?: SchemaObjectWithRef | ReferenceObject;
+  example?: any;
+  examples?: Map<ExampleObject | ReferenceObject>;
+  //
+  content?: Map<MediaTypeObjectWithRef>;
+  // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+  // pipeDelimited and deepObject
+}
+
+export interface RequestBodyObject {
+  description?: string;
+  content: Map<MediaTypeObject>;
+  required?: boolean;
+}
+
+export interface RequestBodyObjectWithRef {
+  description?: string;
+  content: Map<MediaTypeObjectWithRef>;
+  required?: boolean;
+}
+
+export interface MediaTypeObject {
+  schema?: SchemaObject;
+  example?: any;
+  examples?: Map<ExampleObject>;
+  encoding?: Map<EncodingObject>;
+}
+
+export interface MediaTypeObjectWithRef {
+  schema?: SchemaObjectWithRef | ReferenceObject;
+  example?: any;
+  examples?: Map<ExampleObject | ReferenceObject>;
+  encoding?: Map<EncodingObjectWithRef>;
+}
+
+export interface EncodingObject {
+  contentType?: string;
+  headers?: Map<HeaderObject>;
+  style?: string;
+  explode?: boolean;
+  allowReserved?: boolean;
+}
+
+export interface EncodingObjectWithRef {
+  contentType?: string;
+  headers?: Map<HeaderObjectWithRef | ReferenceObject>;
+  style?: string;
+  explode?: boolean;
+  allowReserved?: boolean;
+}
+
+export type ResponsesObject = Map<ResponseObject>;
+
+export type ResponsesObjectWithRef = Map<
+  ResponseObjectWithRef | ReferenceObject
+>;
+
+export interface ResponseObject {
+  description: string;
+  headers?: Map<HeaderObject>;
+  content?: Map<MediaTypeObject>;
+  links?: Map<LinkObject>;
+}
+
+export interface ResponseObjectWithRef {
+  description: string;
+  headers?: Map<HeaderObjectWithRef | ReferenceObject>;
+  content?: Map<MediaTypeObjectWithRef>;
+  links?: Map<LinkObject | ReferenceObject>;
+}
+
+export type CallbackObject = Map<PathItemObject>;
+
+export type CallbackObjectWithRef = Map<PathItemObjectWithRef>;
+
+export interface ExampleObject {
+  summary?: string;
+  description?: string;
+  value?: any;
+  externalValue?: string;
+}
+
+export interface LinkObject {
+  operationRef?: string;
+  operationId?: string;
+  parameters?: Map<any>;
+  requestBody?: any;
+  description?: string;
+  server?: ServerObject;
+}
+
+export type HeaderObject = Omit<ParameterObject, "name" | "in">;
+
+export type HeaderObjectWithRef = Omit<ParameterObjectWithRef, "name" | "in">;
+
+export interface TagObject {
+  name: string;
+  description?: string;
+  externalDocs?: ExternalDocumentationObject;
+  "x-displayName"?: string;
+}
+
+export interface ReferenceObject {
+  $ref: string;
+}
+
+export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+export type SchemaObject = Omit<
+  JSONSchema,
+  | "type"
+  | "allOf"
+  | "oneOf"
+  | "anyOf"
+  | "not"
+  | "items"
+  | "properties"
+  | "additionalProperties"
+> & {
+  // OpenAPI specific overrides
+  type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+  allOf?: SchemaObject[];
+  oneOf?: SchemaObject[];
+  anyOf?: SchemaObject[];
+  not?: SchemaObject;
+  items?: SchemaObject;
+  properties?: Map<SchemaObject>;
+  additionalProperties?: boolean | SchemaObject;
+
+  // OpenAPI additions
+  nullable?: boolean;
+  discriminator?: DiscriminatorObject;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  xml?: XMLObject;
+  externalDocs?: ExternalDocumentationObject;
+  example?: any;
+  deprecated?: boolean;
+};
+
+export type SchemaObjectWithRef = Omit<
+  JSONSchema,
+  | "type"
+  | "allOf"
+  | "oneOf"
+  | "anyOf"
+  | "not"
+  | "items"
+  | "properties"
+  | "additionalProperties"
+> & {
+  // OpenAPI specific overrides
+  type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+  allOf?: (SchemaObject | ReferenceObject)[];
+  oneOf?: (SchemaObject | ReferenceObject)[];
+  anyOf?: (SchemaObject | ReferenceObject)[];
+  not?: SchemaObject | ReferenceObject;
+  items?: SchemaObject | ReferenceObject;
+  properties?: Map<SchemaObject | ReferenceObject>;
+  additionalProperties?: boolean | SchemaObject | ReferenceObject;
+
+  // OpenAPI additions
+  nullable?: boolean;
+  discriminator?: DiscriminatorObject;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  xml?: XMLObject;
+  externalDocs?: ExternalDocumentationObject;
+  example?: any;
+  deprecated?: boolean;
+};
+
+export interface DiscriminatorObject {
+  propertyName: string;
+  mapping?: Map<string>;
+}
+
+export interface XMLObject {
+  name?: string;
+  namespace?: string;
+  prefix?: string;
+  attribute?: boolean;
+  wrapped?: boolean;
+}
+
+export type SecuritySchemeObject =
+  | ApiKeySecuritySchemeObject
+  | HttpSecuritySchemeObject
+  | Oauth2SecuritySchemeObject
+  | OpenIdConnectSecuritySchemeObject;
+
+export interface ApiKeySecuritySchemeObject {
+  type: "apiKey";
+  description?: string;
+  name: string;
+  in: "query" | "header" | "cookie";
+}
+
+export interface HttpSecuritySchemeObject {
+  type: "http";
+  description?: string;
+  scheme: string;
+  bearerFormat?: string;
+}
+
+export interface Oauth2SecuritySchemeObject {
+  type: "oauth2";
+  description?: string;
+  flows: OAuthFlowsObject;
+}
+
+export interface OpenIdConnectSecuritySchemeObject {
+  type: "openIdConnect";
+  description?: string;
+  openIdConnectUrl: string;
+}
+
+export interface OAuthFlowsObject {
+  implicit?: OAuthFlowObject;
+  password?: OAuthFlowObject;
+  clientCredentials?: OAuthFlowObject;
+  authorizationCode?: OAuthFlowObject;
+}
+
+export interface OAuthFlowObject {
+  authorizationUrl?: string; // required for some
+  tokenUrl?: string; // required for some
+  refreshUrl?: string;
+  scopes: Map<string>;
+}
+
+export type SecurityRequirementObject = Map<string[]>;

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 "@paloaltonetworks/openapi-to-postmanv2" {
+  export default any;
+}

package/src/options.ts

@@ -0,0 +1,20 @@
+/* ============================================================================
+ * 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";
+
+import type { PluginOptions } from "./types";
+
+export const DEFAULT_OPTIONS: PluginOptions = {
+  id: "default",
+  config: {},
+};
+
+export const OptionsSchema = Joi.object({
+  id: Joi.string().default(DEFAULT_OPTIONS.id),
+  config: Joi.object().default(DEFAULT_OPTIONS.config),
+});

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/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;
+}