docusaurus-plugin-openapi-docs 0.0.0-1000

package/src/openapi/types.ts

@@ -0,0 +1,455 @@
+/* ============================================================================
+ * 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;
+  swagger?: string;
+  webhooks?: PathsObject;
+  "x-webhooks"?: PathsObject;
+  "x-tagGroups"?: TagGroupObject[];
+}
+
+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;
+  tags?: TagObject[];
+  "x-logo"?: LogoObject;
+  "x-dark-logo"?: LogoObject;
+  logo?: LogoObject;
+  darkLogo?: LogoObject;
+}
+
+export interface LogoObject {
+  url?: 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>;
+  param?: Object;
+  // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+  // pipeDelimited and deepObject
+  "x-enumDescriptions"?: Record<string, string>;
+}
+
+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>;
+  type?: any;
+}
+
+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 TagGroupObject {
+  name: string;
+  tags: 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;
+  "x-tags"?: string[];
+  "x-enumDescriptions"?: Record<string, string>;
+};
+
+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;
+  name?: string;
+  in?: 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/utils/loadAndResolveSpec.ts

@@ -0,0 +1,171 @@
+/* ============================================================================
+ * 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 $RefParser from "@apidevtools/json-schema-ref-parser";
+import { bundle, Config } from "@redocly/openapi-core";
+import type { Source, Document } from "@redocly/openapi-core";
+import { ResolvedConfig } from "@redocly/openapi-core/lib/config";
+import chalk from "chalk";
+// @ts-ignore
+import { convertObj } from "swagger2openapi";
+
+import { OpenApiObject } from "../types";
+import { OpenAPIParser } from "./services/OpenAPIParser";
+
+function serializer(replacer: any, cycleReplacer: any) {
+  var stack: any = [],
+    keys: any = [];
+
+  if (cycleReplacer === undefined)
+    cycleReplacer = function (key: any, value: any) {
+      if (stack[0] === value) return "circular()";
+      return value.title ? `circular(${value.title})` : "circular()";
+    };
+
+  return function (key: any, value: any) {
+    // Resolve discriminator ref pointers
+    if (value?.discriminator !== undefined) {
+      const parser = new OpenAPIParser(stack[0]);
+      if (
+        value.discriminator.mapping &&
+        typeof value.discriminator.mapping === "object"
+      ) {
+        for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+          const discriminator = k as string;
+          if (typeof v === "string" && v.charAt(0) === "#") {
+            const ref = v as string;
+            const resolvedRef = parser.byRef(ref);
+            value.discriminator.mapping[discriminator] = resolvedRef;
+          }
+        }
+      }
+    }
+    if (stack.length > 0) {
+      // @ts-ignore
+      var thisPos = stack.indexOf(this);
+      // @ts-ignore
+      ~thisPos ? stack.splice(thisPos + 1) : stack.push(this);
+      ~thisPos ? keys.splice(thisPos, Infinity, key) : keys.push(key);
+      // @ts-ignore
+      if (~stack.indexOf(value)) value = cycleReplacer.call(this, key, value);
+    } else stack.push(value);
+
+    // @ts-ignore
+    return replacer === undefined ? value : replacer.call(this, key, value);
+  };
+}
+
+export function convertSwagger2OpenAPI(spec: object) {
+  console.warn(
+    "[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0"
+  );
+  return new Promise((resolve, reject) =>
+    convertObj(
+      spec,
+      {
+        patch: true,
+        warnOnly: true,
+        text: "{}",
+        anchors: true,
+        resolveInternal: true,
+      },
+      (err: any, res: any) => {
+        // TODO: log any warnings
+        if (err) {
+          return reject(err);
+        }
+        resolve(res && res.openapi);
+      }
+    )
+  );
+}
+
+async function resolveJsonRefs(specUrlOrObject: object | string) {
+  try {
+    let schema = await $RefParser.dereference(specUrlOrObject, {
+      continueOnError: true,
+      resolve: {
+        file: true,
+        external: true,
+        http: {
+          timeout: 15000, // 15 sec timeout
+        },
+      },
+      dereference: {
+        circular: true,
+      },
+    });
+    return schema as OpenApiObject;
+  } catch (err: any) {
+    let errorMsg = "";
+
+    if (err.errors[0] !== undefined) {
+      const error = err.errors[0];
+      errorMsg = `Error: [${error.message}] with footprint [${error.footprint}]`;
+    } else {
+      errorMsg = err;
+    }
+
+    console.error(chalk.yellow(errorMsg));
+    return;
+  }
+}
+
+export async function loadAndResolveSpec(specUrlOrObject: object | string) {
+  const config = new Config({} as ResolvedConfig);
+  const bundleOpts = {
+    config,
+    base: process.cwd(),
+  } as any;
+
+  if (typeof specUrlOrObject === "object" && specUrlOrObject !== null) {
+    bundleOpts["doc"] = {
+      source: { absoluteRef: "" } as Source,
+      parsed: specUrlOrObject,
+    } as Document;
+  } else {
+    bundleOpts["ref"] = specUrlOrObject;
+  }
+
+  // Force dereference ?
+  // bundleOpts["dereference"] = true;
+
+  const {
+    bundle: { parsed },
+  } = await bundle(bundleOpts);
+
+  //Pre-processing before resolving JSON refs
+  if (parsed.components) {
+    for (let [component, type] of Object.entries(parsed.components) as any) {
+      if (component === "schemas") {
+        for (let [schemaKey, schemaValue] of Object.entries(type) as any) {
+          const title: string | undefined = schemaValue["title"];
+          if (!title) {
+            schemaValue.title = schemaKey;
+          }
+        }
+      }
+    }
+  }
+
+  const resolved = await resolveJsonRefs(parsed);
+
+  // Force serialization and replace circular $ref pointers
+  // @ts-ignore
+  const serialized = JSON.stringify(resolved, serializer());
+  let decycled;
+  try {
+    decycled = JSON.parse(serialized);
+  } catch (err: any) {
+    console.error(chalk.yellow(err));
+  }
+  return decycled !== undefined && typeof decycled === "object"
+    ? decycled.swagger !== undefined
+      ? convertSwagger2OpenAPI(decycled)
+      : decycled
+    : resolved;
+}