docusaurus-plugin-openapi-docs 1.0.5 → 1.1.1

package/lib/openapi/utils/types/open-api.d.ts

@@ -0,0 +1,305 @@
+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 declare 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[];
+}
+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 declare type OpenAPIParameterLocation = "query" | "header" | "path" | "cookie";
+export declare 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 declare 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/lib/openapi/utils/types/open-api.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/utils/JsonPointer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Wrapper for JsonPointer. Provides common operations
+ */
+export declare class JsonPointer {
+    /**
+     * returns last JsonPointer token
+     * if level > 1 returns levels last (second last/third last)
+     * @example
+     * // returns subpath
+     * JsonPointerHelper.baseName('/path/0/subpath')
+     * // returns foo
+     * JsonPointerHelper.baseName('/path/foo/subpath', 2)
+     */
+    static baseName(pointer: any, level?: number): string;
+    /**
+     * returns dirname of pointer
+     * if level > 1 returns corresponding dirname in the hierarchy
+     * @example
+     * // returns /path/0
+     * JsonPointerHelper.dirName('/path/0/subpath')
+     * // returns /path
+     * JsonPointerHelper.dirName('/path/foo/subpath', 2)
+     */
+    static dirName(pointer: any, level?: number): string;
+    /**
+     * returns relative path tokens
+     * @example
+     * // returns ['subpath']
+     * JsonPointerHelper.relative('/path/0', '/path/0/subpath')
+     * // returns ['foo', 'subpath']
+     * JsonPointerHelper.relative('/path', '/path/foo/subpath')
+     */
+    static relative(from: any, to: any): string[];
+    /**
+     * overridden JsonPointer original parse to take care of prefixing '#' symbol
+     * that is not valid JsonPointer
+     */
+    static parse(pointer: any): string[];
+    /**
+     * Creates a JSON pointer path, by joining one or more tokens to a base path.
+     *
+     * @param {string} base - The base path
+     * @param {string|string[]} tokens - The token(s) to append (e.g. ["name", "first"])
+     * @returns {string}
+     */
+    static join(base: any, tokens: any): string;
+    static get(object: object, pointer: string): any;
+    static compile(tokens: string[]): string;
+    static escape(pointer: string): string;
+}
+export default JsonPointer;

package/lib/openapi/utils/utils/JsonPointer.js

@@ -0,0 +1,95 @@
+"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.JsonPointer = void 0;
+const json_pointer_1 = __importDefault(require("json-pointer"));
+const origParse = json_pointer_1.default.parse;
+/**
+ * Wrapper for JsonPointer. Provides common operations
+ */
+class JsonPointer {
+    /**
+     * returns last JsonPointer token
+     * if level > 1 returns levels last (second last/third last)
+     * @example
+     * // returns subpath
+     * JsonPointerHelper.baseName('/path/0/subpath')
+     * // returns foo
+     * JsonPointerHelper.baseName('/path/foo/subpath', 2)
+     */
+    static baseName(pointer, level = 1) {
+        const tokens = JsonPointer.parse(pointer);
+        return tokens[tokens.length - level];
+    }
+    /**
+     * returns dirname of pointer
+     * if level > 1 returns corresponding dirname in the hierarchy
+     * @example
+     * // returns /path/0
+     * JsonPointerHelper.dirName('/path/0/subpath')
+     * // returns /path
+     * JsonPointerHelper.dirName('/path/foo/subpath', 2)
+     */
+    static dirName(pointer, level = 1) {
+        const tokens = JsonPointer.parse(pointer);
+        return json_pointer_1.default.compile(tokens.slice(0, tokens.length - level));
+    }
+    /**
+     * returns relative path tokens
+     * @example
+     * // returns ['subpath']
+     * JsonPointerHelper.relative('/path/0', '/path/0/subpath')
+     * // returns ['foo', 'subpath']
+     * JsonPointerHelper.relative('/path', '/path/foo/subpath')
+     */
+    static relative(from, to) {
+        const fromTokens = JsonPointer.parse(from);
+        const toTokens = JsonPointer.parse(to);
+        return toTokens.slice(fromTokens.length);
+    }
+    /**
+     * overridden JsonPointer original parse to take care of prefixing '#' symbol
+     * that is not valid JsonPointer
+     */
+    static parse(pointer) {
+        let ptr = pointer;
+        if (ptr.charAt(0) === "#") {
+            ptr = ptr.substring(1);
+        }
+        return origParse(ptr);
+    }
+    /**
+     * Creates a JSON pointer path, by joining one or more tokens to a base path.
+     *
+     * @param {string} base - The base path
+     * @param {string|string[]} tokens - The token(s) to append (e.g. ["name", "first"])
+     * @returns {string}
+     */
+    static join(base, tokens) {
+        // TODO: optimize
+        const baseTokens = JsonPointer.parse(base);
+        const resTokens = baseTokens.concat(tokens);
+        return json_pointer_1.default.compile(resTokens);
+    }
+    static get(object, pointer) {
+        return json_pointer_1.default.get(object, pointer);
+    }
+    static compile(tokens) {
+        return json_pointer_1.default.compile(tokens);
+    }
+    static escape(pointer) {
+        return json_pointer_1.default.escape(pointer);
+    }
+}
+exports.JsonPointer = JsonPointer;
+json_pointer_1.default.parse = JsonPointer.parse;
+Object.assign(JsonPointer, json_pointer_1.default);
+exports.default = JsonPointer;

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

@@ -0,0 +1,43 @@
+/**
+ * Maps over array passing `isLast` bool to iterator as the second argument
+ */
+export declare function mapWithLast<T, P>(array: T[], iteratee: (item: T, isLast: boolean) => P): P[];
+/**
+ * Creates an object with the same keys as object and values generated by running each
+ * own enumerable string keyed property of object thru iteratee.
+ * The iteratee is invoked with three arguments: (value, key, object).
+ *
+ * @param object the object to iterate over
+ * @param iteratee the function invoked per iteration.
+ */
+export declare function mapValues<T, P>(object: Record<string, T>, iteratee: (val: T, key: string, obj: Record<string, T>) => P): Record<string, P>;
+/**
+ * flattens collection using `prop` field as a children
+ * @param collectionItems collection items
+ * @param prop item property with child elements
+ */
+export declare function flattenByProp<T extends object, P extends keyof T>(collectionItems: T[], prop: P): T[];
+export declare function stripTrailingSlash(path: string): string;
+export declare function isNumeric(n: any): n is number;
+export declare function appendToMdHeading(md: string, heading: string, content: string): string;
+export declare const mergeObjects: (target: any, ...sources: any[]) => any;
+export declare const isObject: (item: unknown) => item is Record<string, unknown>;
+/**
+ * slugify() returns empty string when failed to slugify.
+ * so try to return minimum slugified-string with failed one which keeps original value
+ * the regex codes are referenced with https://gist.github.com/mathewbyrne/1280286
+ */
+export declare function safeSlugify(value: string): string;
+export declare function isAbsoluteUrl(url: string): boolean;
+/**
+ * simple resolve URL which doesn't break on strings with url fragments
+ * e.g. resolveUrl('http://test.com:{port}', 'path') results in http://test.com:{port}/path
+ */
+export declare function resolveUrl(url: string, to: string): string;
+export declare function getBasePath(serverUrl: string): string;
+export declare function titleize(text: string): string;
+export declare function removeQueryString(serverUrl: string): string;
+export declare function escapeHTMLAttrChars(str: string): string;
+export declare function unescapeHTMLChars(str: string): string;
+export declare function isArray(value: unknown): value is any[];
+export declare function isBoolean(value: unknown): value is boolean;