docusaurus-plugin-openapi-docs 0.0.0-1000

package/lib/openapi/types.d.ts

@@ -0,0 +1,354 @@
+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[];
+    "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[];
+    "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;
+    "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>;
+}
+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"> & {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    allOf?: SchemaObject[];
+    oneOf?: SchemaObject[];
+    anyOf?: SchemaObject[];
+    not?: SchemaObject;
+    items?: SchemaObject;
+    properties?: Map<SchemaObject>;
+    additionalProperties?: boolean | SchemaObject;
+    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"> & {
+    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;
+    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;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Map<string>;
+}
+export type SecurityRequirementObject = Map<string[]>;
+export {};

package/lib/openapi/types.js

@@ -0,0 +1,8 @@
+"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 });

package/lib/openapi/utils/loadAndResolveSpec.d.ts

@@ -0,0 +1,2 @@
+export declare function convertSwagger2OpenAPI(spec: object): Promise<unknown>;
+export declare function loadAndResolveSpec(specUrlOrObject: object | string): Promise<any>;

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -0,0 +1,153 @@
+"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.
+ * ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertSwagger2OpenAPI = convertSwagger2OpenAPI;
+exports.loadAndResolveSpec = loadAndResolveSpec;
+const json_schema_ref_parser_1 = __importDefault(require("@apidevtools/json-schema-ref-parser"));
+const openapi_core_1 = require("@redocly/openapi-core");
+const chalk_1 = __importDefault(require("chalk"));
+// @ts-ignore
+const swagger2openapi_1 = require("swagger2openapi");
+const OpenAPIParser_1 = require("./services/OpenAPIParser");
+function serializer(replacer, cycleReplacer) {
+    var stack = [], keys = [];
+    if (cycleReplacer === undefined)
+        cycleReplacer = function (key, value) {
+            if (stack[0] === value)
+                return "circular()";
+            return value.title ? `circular(${value.title})` : "circular()";
+        };
+    return function (key, value) {
+        // Resolve discriminator ref pointers
+        if ((value === null || value === void 0 ? void 0 : value.discriminator) !== undefined) {
+            const parser = new OpenAPIParser_1.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;
+                    if (typeof v === "string" && v.charAt(0) === "#") {
+                        const ref = v;
+                        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);
+    };
+}
+function convertSwagger2OpenAPI(spec) {
+    console.warn("[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0");
+    return new Promise((resolve, reject) => (0, swagger2openapi_1.convertObj)(spec, {
+        patch: true,
+        warnOnly: true,
+        text: "{}",
+        anchors: true,
+        resolveInternal: true,
+    }, (err, res) => {
+        // TODO: log any warnings
+        if (err) {
+            return reject(err);
+        }
+        resolve(res && res.openapi);
+    }));
+}
+async function resolveJsonRefs(specUrlOrObject) {
+    try {
+        let schema = await json_schema_ref_parser_1.default.dereference(specUrlOrObject, {
+            continueOnError: true,
+            resolve: {
+                file: true,
+                external: true,
+                http: {
+                    timeout: 15000, // 15 sec timeout
+                },
+            },
+            dereference: {
+                circular: true,
+            },
+        });
+        return schema;
+    }
+    catch (err) {
+        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_1.default.yellow(errorMsg));
+        return;
+    }
+}
+async function loadAndResolveSpec(specUrlOrObject) {
+    const config = new openapi_core_1.Config({});
+    const bundleOpts = {
+        config,
+        base: process.cwd(),
+    };
+    if (typeof specUrlOrObject === "object" && specUrlOrObject !== null) {
+        bundleOpts["doc"] = {
+            source: { absoluteRef: "" },
+            parsed: specUrlOrObject,
+        };
+    }
+    else {
+        bundleOpts["ref"] = specUrlOrObject;
+    }
+    // Force dereference ?
+    // bundleOpts["dereference"] = true;
+    const { bundle: { parsed }, } = await (0, openapi_core_1.bundle)(bundleOpts);
+    //Pre-processing before resolving JSON refs
+    if (parsed.components) {
+        for (let [component, type] of Object.entries(parsed.components)) {
+            if (component === "schemas") {
+                for (let [schemaKey, schemaValue] of Object.entries(type)) {
+                    const title = 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) {
+        console.error(chalk_1.default.yellow(err));
+    }
+    return decycled !== undefined && typeof decycled === "object"
+        ? decycled.swagger !== undefined
+            ? convertSwagger2OpenAPI(decycled)
+            : decycled
+        : resolved;
+}

package/lib/openapi/utils/services/OpenAPIParser.d.ts

@@ -0,0 +1,52 @@
+import { OpenAPIRef, OpenAPISchema, OpenAPISpec, Referenced } from "../types";
+export type MergedOpenAPISchema = OpenAPISchema & {
+    parentRefs?: string[];
+};
+/**
+ * Loads and keeps spec. Provides raw spec operations
+ */
+export declare class OpenAPIParser {
+    private options;
+    specUrl?: string;
+    spec: OpenAPISpec;
+    private _refCounter;
+    private allowMergeRefs;
+    constructor(spec: OpenAPISpec, specUrl?: string, options?: {});
+    validate(spec: any): void;
+    /**
+     * get spec part by JsonPointer ($ref)
+     */
+    byRef: <T extends unknown = any>(ref: string) => T | undefined;
+    /**
+     * checks if the object is OpenAPI reference (contains $ref property)
+     */
+    isRef(obj: any): obj is OpenAPIRef;
+    /**
+     * resets visited endpoints. should be run after
+     */
+    resetVisited(): void;
+    exitRef<T>(ref: Referenced<T>): void;
+    /**
+     * Resolve given reference object or return as is if it is not a reference
+     * @param obj object to dereference
+     * @param forceCircular whether to dereference even if it is circular ref
+     */
+    deref<T extends object>(obj: OpenAPIRef | T, forceCircular?: boolean, mergeAsAllOf?: boolean): T;
+    shallowDeref<T extends unknown>(obj: OpenAPIRef | T): T;
+    mergeRefs(ref: any, resolved: any, mergeAsAllOf: boolean): any;
+    /**
+     * Merge allOf constraints.
+     * @param schema schema with allOF
+     * @param $ref pointer of the schema
+     * @param forceCircular whether to dereference children even if it is a circular ref
+     */
+    mergeAllOf(schema: OpenAPISchema, $ref?: string, forceCircular?: boolean, used$Refs?: Set<string>): MergedOpenAPISchema;
+    /**
+     * Find all derived definitions among #/components/schemas from any of $refs
+     * returns map of definition pointer to definition name
+     * @param $refs array of references to find derived from
+     */
+    findDerived($refs: string[]): Record<string, string[] | string>;
+    exitParents(shema: MergedOpenAPISchema): void;
+    private hoistOneOfs;
+}