docusaurus-plugin-openapi-docs 1.0.0

package/lib/markdown/createVersionBadge.js

@@ -0,0 +1,20 @@
+"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 });
+exports.createVersionBadge = void 0;
+const utils_1 = require("./utils");
+function createVersionBadge(version) {
+    return (0, utils_1.guard)(version, (version) => [
+        (0, utils_1.create)("span", {
+            className: "theme-doc-version-badge badge badge--secondary",
+            children: `Version: ${escape(version)}`,
+        }),
+        `\n\n`,
+    ]);
+}
+exports.createVersionBadge = createVersionBadge;

package/lib/markdown/index.d.ts

@@ -0,0 +1,3 @@
+import { ApiPageMetadata, InfoPageMetadata } from "../types";
+export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, parameters, requestBody, responses, }, }: ApiPageMetadata): string;
+export declare function createInfoPageMD({ info: { title, version, description }, }: InfoPageMetadata): string;

package/lib/markdown/index.js

@@ -0,0 +1,43 @@
+"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 });
+exports.createInfoPageMD = exports.createApiPageMD = void 0;
+const lodash_1 = require("lodash");
+const createDeprecationNotice_1 = require("./createDeprecationNotice");
+const createDescription_1 = require("./createDescription");
+const createParamsDetails_1 = require("./createParamsDetails");
+const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
+const createStatusCodes_1 = require("./createStatusCodes");
+const createVersionBadge_1 = require("./createVersionBadge");
+const utils_1 = require("./utils");
+function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, parameters, requestBody, responses, }, }) {
+    return (0, utils_1.render)([
+        `import ParamsItem from "@theme/ParamsItem";\n`,
+        `import SchemaItem from "@theme/SchemaItem"\n`,
+        `import Tabs from "@theme/Tabs";\n`,
+        `import TabItem from "@theme/TabItem";\n\n`,
+        `## ${(0, lodash_1.escape)(title)}\n\n`,
+        (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),
+        (0, createDescription_1.createDescription)((0, lodash_1.escape)(description)),
+        (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "path" }),
+        (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "query" }),
+        (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "header" }),
+        (0, createParamsDetails_1.createParamsDetails)({ parameters, type: "cookie" }),
+        (0, createRequestBodyDetails_1.createRequestBodyDetails)({ title: "Request Body", body: requestBody }),
+        (0, createStatusCodes_1.createStatusCodes)({ responses }),
+    ]);
+}
+exports.createApiPageMD = createApiPageMD;
+function createInfoPageMD({ info: { title, version, description }, }) {
+    return (0, utils_1.render)([
+        (0, createVersionBadge_1.createVersionBadge)(version),
+        `# ${(0, lodash_1.escape)(title)}\n\n`,
+        (0, createDescription_1.createDescription)(description),
+    ]);
+}
+exports.createInfoPageMD = createInfoPageMD;

package/lib/markdown/schema.d.ts

@@ -0,0 +1,3 @@
+import { SchemaObject } from "../openapi/types";
+export declare function getSchemaName(schema: SchemaObject, circular?: boolean): string;
+export declare function getQualifierMessage(schema?: SchemaObject): string | undefined;

package/lib/markdown/schema.js

@@ -0,0 +1,100 @@
+"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 });
+exports.getQualifierMessage = exports.getSchemaName = void 0;
+function prettyName(schema, circular) {
+    var _a, _b, _c;
+    if (schema.$ref) {
+        return schema.$ref.replace("#/components/schemas/", "") + circular
+            ? " (circular)"
+            : "";
+    }
+    if (schema.format) {
+        return schema.format;
+    }
+    if (schema.allOf) {
+        return "object";
+    }
+    if (schema.type === "object") {
+        return (_b = (_a = schema.xml) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : schema.type;
+    }
+    return (_c = schema.title) !== null && _c !== void 0 ? _c : schema.type;
+}
+function getSchemaName(schema, circular) {
+    var _a;
+    if (schema.items) {
+        return prettyName(schema.items, circular) + "[]";
+    }
+    return (_a = prettyName(schema, circular)) !== null && _a !== void 0 ? _a : "";
+}
+exports.getSchemaName = getSchemaName;
+function getQualifierMessage(schema) {
+    // TODO:
+    // - maxItems
+    // - minItems
+    // - uniqueItems
+    // - maxProperties
+    // - minProperties
+    // - multipleOf
+    if (!schema) {
+        return undefined;
+    }
+    if (schema.items) {
+        return getQualifierMessage(schema.items);
+    }
+    let message = "**Possible values:** ";
+    let qualifierGroups = [];
+    if (schema.minLength || schema.maxLength) {
+        let lengthQualifier = "";
+        if (schema.minLength) {
+            lengthQualifier += `${schema.minLength} ≤ `;
+        }
+        lengthQualifier += "length";
+        if (schema.maxLength) {
+            lengthQualifier += ` ≤ ${schema.maxLength}`;
+        }
+        qualifierGroups.push(lengthQualifier);
+    }
+    if (schema.minimum ||
+        schema.maximum ||
+        typeof schema.exclusiveMinimum === "number" ||
+        typeof schema.exclusiveMaximum === "number") {
+        let minmaxQualifier = "";
+        if (typeof schema.exclusiveMinimum === "number") {
+            minmaxQualifier += `${schema.exclusiveMinimum} < `;
+        }
+        else if (schema.minimum && !schema.exclusiveMinimum) {
+            minmaxQualifier += `${schema.minimum} ≤ `;
+        }
+        else if (schema.minimum && schema.exclusiveMinimum === true) {
+            minmaxQualifier += `${schema.minimum} < `;
+        }
+        minmaxQualifier += "value";
+        if (typeof schema.exclusiveMaximum === "number") {
+            minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+        }
+        else if (schema.maximum && !schema.exclusiveMaximum) {
+            minmaxQualifier += ` ≤ ${schema.maximum}`;
+        }
+        else if (schema.maximum && schema.exclusiveMaximum === true) {
+            minmaxQualifier += ` < ${schema.maximum}`;
+        }
+        qualifierGroups.push(minmaxQualifier);
+    }
+    if (schema.pattern) {
+        qualifierGroups.push(`Value must match regular expression \`${schema.pattern}\``);
+    }
+    if (schema.enum) {
+        qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
+    }
+    if (qualifierGroups.length === 0) {
+        return undefined;
+    }
+    return message + qualifierGroups.join(", ");
+}
+exports.getQualifierMessage = getQualifierMessage;

package/lib/markdown/schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/markdown/schema.test.js

@@ -0,0 +1,171 @@
+"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 });
+const schema_1 = require("./schema");
+describe("getQualifierMessage", () => {
+    it("should render nothing", () => {
+        const actual = (0, schema_1.getQualifierMessage)({});
+        expect(actual).toBeUndefined();
+    });
+    //
+    // minLength + maxLength
+    //
+    it("should render minLength", () => {
+        const expected = "**Possible values:** 1 ≤ length";
+        const actual = (0, schema_1.getQualifierMessage)({ minLength: 1 });
+        expect(actual).toBe(expected);
+    });
+    it("should render maxLength", () => {
+        const expected = "**Possible values:** length ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({ maxLength: 40 });
+        expect(actual).toBe(expected);
+    });
+    it("should render minLength and maxLength", () => {
+        const expected = "**Possible values:** 1 ≤ length ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({ minLength: 1, maxLength: 40 });
+        expect(actual).toBe(expected);
+    });
+    //
+    // pattern
+    //
+    it("should render pattern", () => {
+        const expected = "**Possible values:** Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+        const actual = (0, schema_1.getQualifierMessage)({ pattern: "^[a-zA-Z0-9_-]*$" });
+        expect(actual).toBe(expected);
+    });
+    it("should render multiple string qualifiers", () => {
+        const expected = "**Possible values:** 1 ≤ length ≤ 40, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+        const actual = (0, schema_1.getQualifierMessage)({
+            minLength: 1,
+            maxLength: 40,
+            pattern: "^[a-zA-Z0-9_-]*$",
+        });
+        expect(actual).toBe(expected);
+    });
+    //
+    // enum
+    //
+    it("should render enum", () => {
+        const expected = "**Possible values:** [`cat`, `dog`, `mouse`]";
+        const actual = (0, schema_1.getQualifierMessage)({ enum: ["cat", "dog", "mouse"] });
+        expect(actual).toBe(expected);
+    });
+    //
+    // minimum + maximum + exclusiveMinimum + exclusiveMaximum
+    //
+    it("should render minimum", () => {
+        const expected = "**Possible values:** 1 ≤ value";
+        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1 });
+        expect(actual).toBe(expected);
+    });
+    it("should render maximum", () => {
+        const expected = "**Possible values:** value ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({ maximum: 40 });
+        expect(actual).toBe(expected);
+    });
+    it("should render numeric exclusiveMinimum", () => {
+        const expected = "**Possible values:** 1 < value";
+        const actual = (0, schema_1.getQualifierMessage)({ exclusiveMinimum: 1 });
+        expect(actual).toBe(expected);
+    });
+    it("should render numeric exclusiveMaximum", () => {
+        const expected = "**Possible values:** value < 40";
+        const actual = (0, schema_1.getQualifierMessage)({ exclusiveMaximum: 40 });
+        expect(actual).toBe(expected);
+    });
+    it("should render boolean exclusiveMinimum", () => {
+        const expected = "**Possible values:** 1 < value";
+        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, exclusiveMinimum: true });
+        expect(actual).toBe(expected);
+    });
+    it("should render boolean exclusiveMaximum", () => {
+        const expected = "**Possible values:** value < 40";
+        const actual = (0, schema_1.getQualifierMessage)({ maximum: 40, exclusiveMaximum: true });
+        expect(actual).toBe(expected);
+    });
+    it("should render minimum when exclusiveMinimum is false", () => {
+        const expected = "**Possible values:** 1 ≤ value";
+        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, exclusiveMinimum: false });
+        expect(actual).toBe(expected);
+    });
+    it("should render maximum when exclusiveMaximum is false", () => {
+        const expected = "**Possible values:** value ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({
+            maximum: 40,
+            exclusiveMaximum: false,
+        });
+        expect(actual).toBe(expected);
+    });
+    it("should render minimum and maximum", () => {
+        const expected = "**Possible values:** 1 ≤ value ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, maximum: 40 });
+        expect(actual).toBe(expected);
+    });
+    it("should render boolean exclusiveMinimum and maximum", () => {
+        const expected = "**Possible values:** 1 < value ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({
+            minimum: 1,
+            maximum: 40,
+            exclusiveMinimum: true,
+        });
+        expect(actual).toBe(expected);
+    });
+    it("should render minimum and boolean exclusiveMaximum", () => {
+        const expected = "**Possible values:** 1 ≤ value < 40";
+        const actual = (0, schema_1.getQualifierMessage)({
+            minimum: 1,
+            maximum: 40,
+            exclusiveMaximum: true,
+        });
+        expect(actual).toBe(expected);
+    });
+    it("should render numeric exclusiveMinimum and maximum", () => {
+        const expected = "**Possible values:** 1 < value ≤ 40";
+        const actual = (0, schema_1.getQualifierMessage)({
+            exclusiveMinimum: 1,
+            maximum: 40,
+        });
+        expect(actual).toBe(expected);
+    });
+    it("should render minimum and numeric exclusiveMaximum", () => {
+        const expected = "**Possible values:** 1 ≤ value < 40";
+        const actual = (0, schema_1.getQualifierMessage)({
+            minimum: 1,
+            exclusiveMaximum: 40,
+        });
+        expect(actual).toBe(expected);
+    });
+    it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
+        const expected = "**Possible values:** 1 < value < 40";
+        const actual = (0, schema_1.getQualifierMessage)({
+            exclusiveMinimum: 1,
+            maximum: 40,
+            exclusiveMaximum: true,
+        });
+        expect(actual).toBe(expected);
+    });
+    it("should render nothing with empty boolean exclusiveMinimum", () => {
+        const actual = (0, schema_1.getQualifierMessage)({
+            exclusiveMinimum: true,
+        });
+        expect(actual).toBeUndefined();
+    });
+    it("should render nothing with empty boolean exclusiveMaximum", () => {
+        const actual = (0, schema_1.getQualifierMessage)({
+            exclusiveMaximum: true,
+        });
+        expect(actual).toBeUndefined();
+    });
+    it("should render nothing with empty boolean exclusiveMinimum and exclusiveMaximum", () => {
+        const actual = (0, schema_1.getQualifierMessage)({
+            exclusiveMinimum: true,
+            exclusiveMaximum: true,
+        });
+        expect(actual).toBeUndefined();
+    });
+});

package/lib/markdown/utils.d.ts

@@ -0,0 +1,7 @@
+export declare type Children = string | undefined | (string | undefined)[];
+export declare type Props = Record<string, any> & {
+    children?: Children;
+};
+export declare function create(tag: string, props: Props): string;
+export declare function guard<T>(value: T | undefined, cb: (value: T) => Children): string;
+export declare function render(children: Children): string;

package/lib/markdown/utils.js

@@ -0,0 +1,33 @@
+"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 });
+exports.render = exports.guard = exports.create = void 0;
+function create(tag, props) {
+    const { children, ...rest } = props;
+    let propString = "";
+    for (const [key, value] of Object.entries(rest)) {
+        propString += ` ${key}={${JSON.stringify(value)}}`;
+    }
+    return `<${tag}${propString}>${render(children)}</${tag}>`;
+}
+exports.create = create;
+function guard(value, cb) {
+    if (value) {
+        const children = cb(value);
+        return render(children);
+    }
+    return "";
+}
+exports.guard = guard;
+function render(children) {
+    if (Array.isArray(children)) {
+        return children.filter((c) => c !== undefined).join("");
+    }
+    return children !== null && children !== void 0 ? children : "";
+}
+exports.render = render;

package/lib/openapi/createExample.d.ts

@@ -0,0 +1,2 @@
+import { SchemaObject } from "./types";
+export declare const sampleFromSchema: (schema?: SchemaObject) => any;

package/lib/openapi/createExample.js

@@ -0,0 +1,113 @@
+"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 });
+exports.sampleFromSchema = void 0;
+const primitives = {
+    string: {
+        default: () => "string",
+        email: () => "user@example.com",
+        date: () => new Date().toISOString().substring(0, 10),
+        uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+        hostname: () => "example.com",
+        ipv4: () => "198.51.100.42",
+        ipv6: () => "2001:0db8:5b96:0000:0000:426f:8e17:642a",
+    },
+    number: {
+        default: () => 0,
+        float: () => 0.0,
+    },
+    integer: {
+        default: () => 0,
+    },
+    boolean: {
+        default: (schema) => typeof schema.default === "boolean" ? schema.default : true,
+    },
+    object: {},
+    array: {},
+};
+const sampleFromSchema = (schema = {}) => {
+    let { type, example, allOf, properties, items } = schema;
+    if (example !== undefined) {
+        return example;
+    }
+    if (allOf) {
+        // TODO: We are just assuming it will always be an object for now
+        let obj = {
+            type: "object",
+            properties: {},
+            required: [], // NOTE: We shouldn't need to worry about required
+        };
+        for (let item of allOf) {
+            if (item.properties) {
+                obj.properties = {
+                    ...obj.properties,
+                    ...item.properties,
+                };
+            }
+        }
+        return (0, exports.sampleFromSchema)(obj);
+    }
+    if (!type) {
+        if (properties) {
+            type = "object";
+        }
+        else if (items) {
+            type = "array";
+        }
+        else {
+            return;
+        }
+    }
+    if (type === "object") {
+        let obj = {};
+        for (let [name, prop] of Object.entries(properties !== null && properties !== void 0 ? properties : {})) {
+            if (prop.deprecated) {
+                continue;
+            }
+            obj[name] = (0, exports.sampleFromSchema)(prop);
+        }
+        return obj;
+    }
+    if (type === "array") {
+        if (Array.isArray(items === null || items === void 0 ? void 0 : items.anyOf)) {
+            return items === null || items === void 0 ? void 0 : items.anyOf.map((item) => (0, exports.sampleFromSchema)(item));
+        }
+        if (Array.isArray(items === null || items === void 0 ? void 0 : items.oneOf)) {
+            return items === null || items === void 0 ? void 0 : items.oneOf.map((item) => (0, exports.sampleFromSchema)(item));
+        }
+        return [(0, exports.sampleFromSchema)(items)];
+    }
+    if (schema.enum) {
+        if (schema.default) {
+            return schema.default;
+        }
+        return normalizeArray(schema.enum)[0];
+    }
+    return primitive(schema);
+};
+exports.sampleFromSchema = sampleFromSchema;
+function primitive(schema = {}) {
+    let { type, format } = schema;
+    if (type === undefined) {
+        return;
+    }
+    let fn = primitives[type].default;
+    if (format !== undefined) {
+        fn = primitives[type][format] || fn;
+    }
+    if (fn) {
+        return fn(schema);
+    }
+    return "Unknown Type: " + schema.type;
+}
+function normalizeArray(arr) {
+    if (Array.isArray(arr)) {
+        return arr;
+    }
+    return [arr];
+}

package/lib/openapi/index.d.ts

@@ -0,0 +1 @@
+export { readOpenapiFiles, processOpenapiFiles } from "./openapi";

package/lib/openapi/index.js

@@ -0,0 +1,12 @@
+"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 });
+exports.processOpenapiFiles = exports.readOpenapiFiles = void 0;
+var openapi_1 = require("./openapi");
+Object.defineProperty(exports, "readOpenapiFiles", { enumerable: true, get: function () { return openapi_1.readOpenapiFiles; } });
+Object.defineProperty(exports, "processOpenapiFiles", { enumerable: true, get: function () { return openapi_1.processOpenapiFiles; } });

package/lib/openapi/openapi.d.ts

@@ -0,0 +1,11 @@
+import { ApiMetadata } from "../types";
+import { OpenApiObjectWithRef } from "./types";
+interface OpenApiFiles {
+    source: string;
+    sourceDirName: string;
+    data: OpenApiObjectWithRef;
+}
+export declare function readOpenapiFiles(openapiPath: string, _options: {}): Promise<OpenApiFiles[]>;
+export declare function processOpenapiFiles(files: OpenApiFiles[]): Promise<ApiMetadata[]>;
+export declare function processOpenapiFile(openapiDataWithRefs: OpenApiObjectWithRef): Promise<ApiMetadata[]>;
+export {};