docusaurus-plugin-openapi-docs 1.0.6 → 1.1.2

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;

package/lib/openapi/utils/utils/helpers.js

@@ -0,0 +1,230 @@
+"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.isBoolean = exports.isArray = exports.unescapeHTMLChars = exports.escapeHTMLAttrChars = exports.removeQueryString = exports.titleize = exports.getBasePath = exports.resolveUrl = exports.isAbsoluteUrl = exports.safeSlugify = exports.isObject = exports.mergeObjects = exports.appendToMdHeading = exports.isNumeric = exports.stripTrailingSlash = exports.flattenByProp = exports.mapValues = exports.mapWithLast = void 0;
+// @ts-nocheck
+const slugify_1 = __importDefault(require("slugify"));
+/**
+ * Maps over array passing `isLast` bool to iterator as the second argument
+ */
+function mapWithLast(array, iteratee) {
+    const res = [];
+    for (let i = 0; i < array.length - 1; i++) {
+        res.push(iteratee(array[i], false));
+    }
+    if (array.length !== 0) {
+        res.push(iteratee(array[array.length - 1], true));
+    }
+    return res;
+}
+exports.mapWithLast = mapWithLast;
+/**
+ * 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.
+ */
+function mapValues(object, iteratee) {
+    const res = {};
+    for (const key in object) {
+        if (object.hasOwnProperty(key)) {
+            res[key] = iteratee(object[key], key, object);
+        }
+    }
+    return res;
+}
+exports.mapValues = mapValues;
+/**
+ * flattens collection using `prop` field as a children
+ * @param collectionItems collection items
+ * @param prop item property with child elements
+ */
+function flattenByProp(collectionItems, prop) {
+    const res = [];
+    const iterate = (items) => {
+        for (const item of items) {
+            res.push(item);
+            if (item[prop]) {
+                iterate(item[prop]);
+            }
+        }
+    };
+    iterate(collectionItems);
+    return res;
+}
+exports.flattenByProp = flattenByProp;
+function stripTrailingSlash(path) {
+    if (path.endsWith("/")) {
+        return path.substring(0, path.length - 1);
+    }
+    return path;
+}
+exports.stripTrailingSlash = stripTrailingSlash;
+function isNumeric(n) {
+    return !isNaN(parseFloat(n)) && isFinite(n);
+}
+exports.isNumeric = isNumeric;
+function appendToMdHeading(md, heading, content) {
+    // if  heading is already in md and append to the end of it
+    const testRegex = new RegExp(`(^|\\n)#\\s?${heading}\\s*\\n`, "i");
+    const replaceRegex = new RegExp(`((\\n|^)#\\s*${heading}\\s*(\\n|$)(?:.|\\n)*?)(\\n#|$)`, "i");
+    if (testRegex.test(md)) {
+        return md.replace(replaceRegex, `$1\n\n${content}\n$4`);
+    }
+    else {
+        // else append heading itself
+        const br = md === "" || md.endsWith("\n\n") ? "" : md.endsWith("\n") ? "\n" : "\n\n";
+        return `${md}${br}# ${heading}\n\n${content}`;
+    }
+}
+exports.appendToMdHeading = appendToMdHeading;
+// credits https://stackoverflow.com/a/46973278/1749888
+const mergeObjects = (target, ...sources) => {
+    if (!sources.length) {
+        return target;
+    }
+    const source = sources.shift();
+    if (source === undefined) {
+        return target;
+    }
+    if (isMergebleObject(target) && isMergebleObject(source)) {
+        Object.keys(source).forEach((key) => {
+            if (isMergebleObject(source[key])) {
+                if (!target[key]) {
+                    target[key] = {};
+                }
+                (0, exports.mergeObjects)(target[key], source[key]);
+            }
+            else {
+                target[key] = source[key];
+            }
+        });
+    }
+    return (0, exports.mergeObjects)(target, ...sources);
+};
+exports.mergeObjects = mergeObjects;
+const isObject = (item) => {
+    return item !== null && typeof item === "object";
+};
+exports.isObject = isObject;
+const isMergebleObject = (item) => {
+    return (0, exports.isObject)(item) && !isArray(item);
+};
+/**
+ * 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
+ */
+function safeSlugify(value) {
+    return ((0, slugify_1.default)(value) ||
+        value
+            .toString()
+            .toLowerCase()
+            .replace(/\s+/g, "-") // Replace spaces with -
+            .replace(/&/g, "-and-") // Replace & with 'and'
+            .replace(/--+/g, "-") // Replace multiple - with single -
+            .replace(/^-+/, "") // Trim - from start of text
+            .replace(/-+$/, "")); // Trim - from end of text
+}
+exports.safeSlugify = safeSlugify;
+function isAbsoluteUrl(url) {
+    return /(?:^[a-z][a-z0-9+.-]*:|\/\/)/i.test(url);
+}
+exports.isAbsoluteUrl = isAbsoluteUrl;
+/**
+ * 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
+ */
+function resolveUrl(url, to) {
+    let res;
+    if (to.startsWith("//")) {
+        try {
+            res = `${new URL(url).protocol || "https:"}${to}`;
+        }
+        catch {
+            res = `https:${to}`;
+        }
+    }
+    else if (isAbsoluteUrl(to)) {
+        res = to;
+    }
+    else if (!to.startsWith("/")) {
+        res = stripTrailingSlash(url) + "/" + to;
+    }
+    else {
+        try {
+            const urlObj = new URL(url);
+            urlObj.pathname = to;
+            res = urlObj.href;
+        }
+        catch {
+            res = to;
+        }
+    }
+    return stripTrailingSlash(res);
+}
+exports.resolveUrl = resolveUrl;
+function getBasePath(serverUrl) {
+    try {
+        return parseURL(serverUrl).pathname;
+    }
+    catch (e) {
+        // when using with redoc-cli serverUrl can be empty resulting in crash
+        return serverUrl;
+    }
+}
+exports.getBasePath = getBasePath;
+function titleize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+exports.titleize = titleize;
+function removeQueryString(serverUrl) {
+    try {
+        const url = parseURL(serverUrl);
+        url.search = "";
+        return url.toString();
+    }
+    catch (e) {
+        // when using with redoc-cli serverUrl can be empty resulting in crash
+        return serverUrl;
+    }
+}
+exports.removeQueryString = removeQueryString;
+function parseURL(url) {
+    if (typeof URL === "undefined") {
+        // node
+        return new (require("url").URL)(url);
+    }
+    else {
+        return new URL(url);
+    }
+}
+function escapeHTMLAttrChars(str) {
+    return str.replace(/["\\]/g, "\\$&");
+}
+exports.escapeHTMLAttrChars = escapeHTMLAttrChars;
+function unescapeHTMLChars(str) {
+    return str
+        .replace(/&#(\d+);/g, (_m, code) => String.fromCharCode(parseInt(code, 10)))
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"');
+}
+exports.unescapeHTMLChars = unescapeHTMLChars;
+function isArray(value) {
+    return Array.isArray(value);
+}
+exports.isArray = isArray;
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+exports.isBoolean = isBoolean;

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

@@ -0,0 +1,3 @@
+export * from "./JsonPointer";
+export * from "./openapi";
+export * from "./helpers";

package/lib/openapi/utils/utils/index.js

@@ -0,0 +1,25 @@
+"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 __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./JsonPointer"), exports);
+__exportStar(require("./openapi"), exports);
+__exportStar(require("./helpers"), exports);

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

@@ -0,0 +1,40 @@
+import { OpenAPIParser } from "../services/OpenAPIParser";
+import { OpenAPIEncoding, OpenAPIMediaType, OpenAPIParameter, OpenAPIRequestBody, OpenAPIResponse, OpenAPISchema, OpenAPIServer, Referenced } from "../types";
+export declare function isStatusCode(statusCode: string): boolean;
+export declare function getStatusCodeType(statusCode: string | number, defaultAsError?: boolean): string;
+export declare function isOperationName(key: string): boolean;
+export declare function getOperationSummary(operation: any): string;
+export declare function detectType(schema: OpenAPISchema): string;
+export declare function isPrimitiveType(schema: OpenAPISchema, type?: string | string[] | undefined): any;
+export declare function isJsonLike(contentType: string): boolean;
+export declare function isFormUrlEncoded(contentType: string): boolean;
+export declare function urlFormEncodePayload(payload: object, encoding?: {
+    [field: string]: OpenAPIEncoding;
+}): string;
+export declare function serializeParameterValueWithMime(value: any, mime: string): string;
+export declare function serializeParameterValue(parameter: OpenAPIParameter & {
+    serializationMime?: string;
+}, value: any): string;
+export declare function getSerializedValue(field: any, example: any): any;
+export declare function langFromMime(contentType: string): string;
+export declare function isNamedDefinition(pointer?: string): boolean;
+export declare function getDefinitionName(pointer?: string): string | undefined;
+export declare function humanizeNumberRange(schema: OpenAPISchema): string | undefined;
+export declare function humanizeConstraints(schema: OpenAPISchema): string[];
+export declare function sortByRequired(fields: any[], order?: string[]): any[];
+export declare function sortByField(fields: any[], param: "name" | "description" | "kind"): any[];
+export declare function mergeParams(parser: OpenAPIParser, pathParams?: Array<Referenced<OpenAPIParameter>>, operationParams?: Array<Referenced<OpenAPIParameter>>): Array<Referenced<OpenAPIParameter>>;
+export declare function mergeSimilarMediaTypes(types: Record<string, OpenAPIMediaType>): Record<string, OpenAPIMediaType>;
+export declare function expandDefaultServerVariables(url: string, variables?: object): string;
+export declare function normalizeServers(specUrl: string | undefined, servers: OpenAPIServer[]): OpenAPIServer[];
+export declare const SECURITY_DEFINITIONS_JSX_NAME = "SecurityDefinitions";
+export declare const SCHEMA_DEFINITION_JSX_NAME = "SchemaDefinition";
+export declare let SECURITY_SCHEMES_SECTION_PREFIX: string;
+export declare function setSecuritySchemePrefix(prefix: string): void;
+export declare const shortenHTTPVerb: (verb: any) => any;
+export declare function isRedocExtension(key: string): boolean;
+export declare function extractExtensions(obj: object, showExtensions: string[] | true): Record<string, any>;
+export declare function pluralizeType(displayType: string): string;
+export declare function getContentWithLegacyExamples(info: OpenAPIRequestBody | OpenAPIResponse): {
+    [mime: string]: OpenAPIMediaType;
+} | undefined;