docusaurus-plugin-openapi-docs 1.0.6 → 1.1.2

package/src/openapi/utils/services/RedocNormalizedOptions.ts

@@ -0,0 +1,330 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// @ts-nocheck
+
+import { isArray } from "../utils/helpers";
+
+export enum SideNavStyleEnum {
+  SummaryOnly = "summary-only",
+  PathOnly = "path-only",
+  IdOnly = "id-only",
+}
+
+export interface RedocRawOptions {
+  scrollYOffset?: number | string | (() => number);
+  hideHostname?: boolean | string;
+  expandResponses?: string | "all";
+  requiredPropsFirst?: boolean | string;
+  sortPropsAlphabetically?: boolean | string;
+  sortEnumValuesAlphabetically?: boolean | string;
+  sortOperationsAlphabetically?: boolean | string;
+  sortTagsAlphabetically?: boolean | string;
+  nativeScrollbars?: boolean | string;
+  pathInMiddlePanel?: boolean | string;
+  untrustedSpec?: boolean | string;
+  hideLoading?: boolean | string;
+  hideDownloadButton?: boolean | string;
+  downloadFileName?: string;
+  downloadDefinitionUrl?: string;
+  disableSearch?: boolean | string;
+  onlyRequiredInSamples?: boolean | string;
+  showExtensions?: boolean | string | string[];
+  sideNavStyle?: SideNavStyleEnum;
+  hideSingleRequestSampleTab?: boolean | string;
+  menuToggle?: boolean | string;
+  jsonSampleExpandLevel?: number | string | "all";
+  hideSchemaTitles?: boolean | string;
+  simpleOneOfTypeLabel?: boolean | string;
+  payloadSampleIdx?: number;
+  expandSingleSchemaField?: boolean | string;
+  schemaExpansionLevel?: number | string | "all";
+  showObjectSchemaExamples?: boolean | string;
+  showSecuritySchemeType?: boolean;
+  hideSecuritySection?: boolean;
+
+  unstable_ignoreMimeParameters?: boolean;
+
+  enumSkipQuotes?: boolean | string;
+
+  expandDefaultServerVariables?: boolean;
+  maxDisplayedEnumValues?: number;
+  ignoreNamedSchemas?: string[] | string;
+  hideSchemaPattern?: boolean;
+  generatedPayloadSamplesMaxDepth?: number;
+  nonce?: string;
+  hideFab?: boolean;
+  minCharacterLengthToInitSearch?: number;
+  showWebhookVerb?: boolean;
+}
+
+export function argValueToBoolean(
+  val?: string | boolean,
+  defaultValue?: boolean
+): boolean {
+  if (val === undefined) {
+    return defaultValue || false;
+  }
+  if (typeof val === "string") {
+    return val !== "false";
+  }
+  return val;
+}
+
+function argValueToNumber(
+  value: number | string | undefined
+): number | undefined {
+  if (typeof value === "string") {
+    return parseInt(value, 10);
+  }
+
+  if (typeof value === "number") {
+    return value;
+  }
+}
+
+function argValueToExpandLevel(
+  value?: number | string | undefined,
+  defaultValue = 0
+): number {
+  if (value === "all") return Infinity;
+
+  return argValueToNumber(value) || defaultValue;
+}
+
+export class RedocNormalizedOptions {
+  static normalizeExpandResponses(value: RedocRawOptions["expandResponses"]) {
+    if (value === "all") {
+      return "all";
+    }
+    if (typeof value === "string") {
+      const res = {};
+      value.split(",").forEach((code) => {
+        res[code.trim()] = true;
+      });
+      return res;
+    } else if (value !== undefined) {
+      console.warn(
+        `expandResponses must be a string but received value "${value}" of type ${typeof value}`
+      );
+    }
+    return {};
+  }
+
+  static normalizeHideHostname(
+    value: RedocRawOptions["hideHostname"]
+  ): boolean {
+    return !!value;
+  }
+
+  static normalizeShowExtensions(
+    value: RedocRawOptions["showExtensions"]
+  ): string[] | boolean {
+    if (typeof value === "undefined") {
+      return false;
+    }
+    if (value === "") {
+      return true;
+    }
+
+    if (typeof value !== "string") {
+      return value;
+    }
+
+    switch (value) {
+      case "true":
+        return true;
+      case "false":
+        return false;
+      default:
+        return value.split(",").map((ext) => ext.trim());
+    }
+  }
+
+  static normalizeSideNavStyle(
+    value: RedocRawOptions["sideNavStyle"]
+  ): SideNavStyleEnum {
+    const defaultValue = SideNavStyleEnum.SummaryOnly;
+    if (typeof value !== "string") {
+      return defaultValue;
+    }
+
+    switch (value) {
+      case defaultValue:
+        return value;
+      case SideNavStyleEnum.PathOnly:
+        return SideNavStyleEnum.PathOnly;
+      case SideNavStyleEnum.IdOnly:
+        return SideNavStyleEnum.IdOnly;
+      default:
+        return defaultValue;
+    }
+  }
+
+  static normalizePayloadSampleIdx(
+    value: RedocRawOptions["payloadSampleIdx"]
+  ): number {
+    if (typeof value === "number") {
+      return Math.max(0, value); // always greater or equal than 0
+    }
+
+    if (typeof value === "string") {
+      return isFinite(value) ? parseInt(value, 10) : 0;
+    }
+
+    return 0;
+  }
+
+  private static normalizeJsonSampleExpandLevel(
+    level?: number | string | "all"
+  ): number {
+    if (level === "all") {
+      return +Infinity;
+    }
+    if (!isNaN(Number(level))) {
+      return Math.ceil(Number(level));
+    }
+    return 2;
+  }
+
+  private static normalizeGeneratedPayloadSamplesMaxDepth(
+    value?: number | string | undefined
+  ): number {
+    if (!isNaN(Number(value))) {
+      return Math.max(0, Number(value));
+    }
+
+    return 10;
+  }
+
+  hideHostname: boolean;
+  expandResponses: { [code: string]: boolean } | "all";
+  requiredPropsFirst: boolean;
+  sortPropsAlphabetically: boolean;
+  sortEnumValuesAlphabetically: boolean;
+  sortOperationsAlphabetically: boolean;
+  sortTagsAlphabetically: boolean;
+  nativeScrollbars: boolean;
+  pathInMiddlePanel: boolean;
+  untrustedSpec: boolean;
+  hideDownloadButton: boolean;
+  downloadFileName?: string;
+  downloadDefinitionUrl?: string;
+  disableSearch: boolean;
+  onlyRequiredInSamples: boolean;
+  showExtensions: boolean | string[];
+  sideNavStyle: SideNavStyleEnum;
+  hideSingleRequestSampleTab: boolean;
+  menuToggle: boolean;
+  jsonSampleExpandLevel: number;
+  enumSkipQuotes: boolean;
+  hideSchemaTitles: boolean;
+  simpleOneOfTypeLabel: boolean;
+  payloadSampleIdx: number;
+  expandSingleSchemaField: boolean;
+  schemaExpansionLevel: number;
+  showObjectSchemaExamples: boolean;
+  showSecuritySchemeType?: boolean;
+  hideSecuritySection?: boolean;
+
+  /* tslint:disable-next-line */
+  unstable_ignoreMimeParameters: boolean;
+
+  expandDefaultServerVariables: boolean;
+  maxDisplayedEnumValues?: number;
+
+  ignoreNamedSchemas: Set<string>;
+  hideSchemaPattern: boolean;
+  generatedPayloadSamplesMaxDepth: number;
+  hideFab: boolean;
+  minCharacterLengthToInitSearch: number;
+  showWebhookVerb: boolean;
+
+  nonce?: string;
+
+  constructor(raw: RedocRawOptions, defaults: RedocRawOptions = {}) {
+    raw = { ...defaults, ...raw };
+
+    this.hideHostname = RedocNormalizedOptions.normalizeHideHostname(
+      raw.hideHostname
+    );
+    this.expandResponses = RedocNormalizedOptions.normalizeExpandResponses(
+      raw.expandResponses
+    );
+    this.requiredPropsFirst = argValueToBoolean(raw.requiredPropsFirst);
+    this.sortPropsAlphabetically = argValueToBoolean(
+      raw.sortPropsAlphabetically
+    );
+    this.sortEnumValuesAlphabetically = argValueToBoolean(
+      raw.sortEnumValuesAlphabetically
+    );
+    this.sortOperationsAlphabetically = argValueToBoolean(
+      raw.sortOperationsAlphabetically
+    );
+    this.sortTagsAlphabetically = argValueToBoolean(raw.sortTagsAlphabetically);
+    this.nativeScrollbars = argValueToBoolean(raw.nativeScrollbars);
+    this.pathInMiddlePanel = argValueToBoolean(raw.pathInMiddlePanel);
+    this.untrustedSpec = argValueToBoolean(raw.untrustedSpec);
+    this.hideDownloadButton = argValueToBoolean(raw.hideDownloadButton);
+    this.downloadFileName = raw.downloadFileName;
+    this.downloadDefinitionUrl = raw.downloadDefinitionUrl;
+    this.disableSearch = argValueToBoolean(raw.disableSearch);
+    this.onlyRequiredInSamples = argValueToBoolean(raw.onlyRequiredInSamples);
+    this.showExtensions = RedocNormalizedOptions.normalizeShowExtensions(
+      raw.showExtensions
+    );
+    this.sideNavStyle = RedocNormalizedOptions.normalizeSideNavStyle(
+      raw.sideNavStyle
+    );
+    this.hideSingleRequestSampleTab = argValueToBoolean(
+      raw.hideSingleRequestSampleTab
+    );
+    this.menuToggle = argValueToBoolean(raw.menuToggle, true);
+    this.jsonSampleExpandLevel =
+      RedocNormalizedOptions.normalizeJsonSampleExpandLevel(
+        raw.jsonSampleExpandLevel
+      );
+    this.enumSkipQuotes = argValueToBoolean(raw.enumSkipQuotes);
+    this.hideSchemaTitles = argValueToBoolean(raw.hideSchemaTitles);
+    this.simpleOneOfTypeLabel = argValueToBoolean(raw.simpleOneOfTypeLabel);
+    this.payloadSampleIdx = RedocNormalizedOptions.normalizePayloadSampleIdx(
+      raw.payloadSampleIdx
+    );
+    this.expandSingleSchemaField = argValueToBoolean(
+      raw.expandSingleSchemaField
+    );
+    this.schemaExpansionLevel = argValueToExpandLevel(raw.schemaExpansionLevel);
+    this.showObjectSchemaExamples = argValueToBoolean(
+      raw.showObjectSchemaExamples
+    );
+    this.showSecuritySchemeType = argValueToBoolean(raw.showSecuritySchemeType);
+    this.hideSecuritySection = argValueToBoolean(raw.hideSecuritySection);
+
+    this.unstable_ignoreMimeParameters = argValueToBoolean(
+      raw.unstable_ignoreMimeParameters
+    );
+
+    this.expandDefaultServerVariables = argValueToBoolean(
+      raw.expandDefaultServerVariables
+    );
+    this.maxDisplayedEnumValues = argValueToNumber(raw.maxDisplayedEnumValues);
+    const ignoreNamedSchemas = isArray(raw.ignoreNamedSchemas)
+      ? raw.ignoreNamedSchemas
+      : raw.ignoreNamedSchemas?.split(",").map((s) => s.trim());
+    this.ignoreNamedSchemas = new Set(ignoreNamedSchemas);
+    this.hideSchemaPattern = argValueToBoolean(raw.hideSchemaPattern);
+    this.generatedPayloadSamplesMaxDepth =
+      RedocNormalizedOptions.normalizeGeneratedPayloadSamplesMaxDepth(
+        raw.generatedPayloadSamplesMaxDepth
+      );
+    this.nonce = raw.nonce;
+    this.hideFab = argValueToBoolean(raw.hideFab);
+    this.minCharacterLengthToInitSearch =
+      argValueToNumber(raw.minCharacterLengthToInitSearch) || 3;
+    this.showWebhookVerb = argValueToBoolean(raw.showWebhookVerb);
+  }
+}

package/src/openapi/utils/types/index.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.
+ * ========================================================================== */
+
+export * from "./open-api";
+
+export type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;

package/src/openapi/utils/types/open-api.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.
+ * ========================================================================== */
+
+import { Omit } from "./index";
+
+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;
+}