docusaurus-plugin-openapi-docs 0.0.0-348 → 0.0.0-351

package/lib/markdown/createSchemaDetails.js

@@ -0,0 +1,244 @@
+"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.createSchemaDetails = void 0;
+const createDescription_1 = require("./createDescription");
+const createDetails_1 = require("./createDetails");
+const createDetailsSummary_1 = require("./createDetailsSummary");
+const schema_1 = require("./schema");
+const utils_1 = require("./utils");
+const mergeAllOf = require("json-schema-merge-allof");
+function resolveAllOf(allOf) {
+    // Use external library to resolve and merge nested allOf schemas
+    let properties = {};
+    const mergedSchemas = mergeAllOf(allOf, {
+        resolvers: {
+            readOnly: function () {
+                return true;
+            },
+            example: function () {
+                return true;
+            },
+        },
+    });
+    if (mergedSchemas.properties) {
+        properties = mergedSchemas.properties;
+    }
+    const required = allOf.reduce((acc, cur) => {
+        if (Array.isArray(cur.required)) {
+            const next = [...acc, ...cur.required];
+            return next;
+        }
+        return acc;
+    }, []);
+    return { properties, required };
+}
+function createRow({ name, schema, required }) {
+    const schemaName = (0, schema_1.getSchemaName)(schema, true);
+    if (schemaName && (schemaName === "object" || schemaName === "object[]")) {
+        return (0, utils_1.create)("SchemaItem", {
+            collapsible: true,
+            className: "schemaItem",
+            children: [
+                (0, createDetails_1.createDetails)({
+                    children: [
+                        (0, createDetailsSummary_1.createDetailsSummary)({
+                            children: [
+                                (0, utils_1.create)("strong", { children: name }),
+                                (0, utils_1.create)("span", {
+                                    style: { opacity: "0.6" },
+                                    children: ` ${schemaName}`,
+                                }),
+                                (0, utils_1.guard)(required, () => [
+                                    (0, utils_1.create)("strong", {
+                                        style: {
+                                            fontSize: "var(--ifm-code-font-size)",
+                                            color: "var(--openapi-required)",
+                                        },
+                                        children: " required",
+                                    }),
+                                ]),
+                            ],
+                        }),
+                        (0, utils_1.create)("div", {
+                            style: { marginLeft: "1rem" },
+                            children: [
+                                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
+                                    style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                    children: (0, createDescription_1.createDescription)(message),
+                                })),
+                                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                                    style: { marginTop: ".5rem", marginBottom: ".5rem" },
+                                    children: (0, createDescription_1.createDescription)(description),
+                                })),
+                                createRows({ schema: schema }),
+                            ],
+                        }),
+                    ],
+                }),
+            ],
+        });
+    }
+    return (0, utils_1.create)("SchemaItem", {
+        collapsible: false,
+        name,
+        required,
+        schemaDescription: schema.description,
+        schemaName: (0, schema_1.getSchemaName)(schema, true),
+        qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
+    });
+}
+function createRows({ schema }) {
+    // object
+    if (schema.properties !== undefined) {
+        return (0, utils_1.create)("ul", {
+            children: Object.entries(schema.properties).map(([key, val]) => createRow({
+                name: key,
+                schema: val,
+                required: Array.isArray(schema.required)
+                    ? schema.required.includes(key)
+                    : false,
+            })),
+        });
+    }
+    // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
+    if (schema.allOf !== undefined) {
+        const { properties, required } = resolveAllOf(schema.allOf);
+        return (0, utils_1.create)("div", {
+            children: [
+                (0, utils_1.create)("span", {
+                    className: "badge badge--info",
+                    style: { marginBottom: "1rem" },
+                    children: "allOf",
+                }),
+                (0, utils_1.create)("ul", {
+                    className: "allOf",
+                    children: Object.entries(properties).map(([key, val]) => createRow({
+                        name: key,
+                        schema: val,
+                        required: Array.isArray(required)
+                            ? required.includes(key)
+                            : false,
+                    })),
+                }),
+            ],
+        });
+    }
+    // array
+    if (schema.items !== undefined) {
+        return createRows({ schema: schema.items });
+    }
+    // primitive
+    return undefined;
+}
+function createRowsRoot({ schema }) {
+    // object
+    if (schema.properties !== undefined) {
+        return Object.entries(schema.properties).map(([key, val]) => createRow({
+            name: key,
+            schema: val,
+            required: Array.isArray(schema.required)
+                ? schema.required.includes(key)
+                : false,
+        }));
+    }
+    // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
+    if (schema.allOf !== undefined) {
+        const { properties, required } = resolveAllOf(schema.allOf);
+        return Object.entries(properties).map(([key, val]) => createRow({
+            name: key,
+            schema: val,
+            required: Array.isArray(required) ? required.includes(key) : false,
+        }));
+    }
+    // array
+    if (schema.items !== undefined) {
+        return (0, utils_1.create)("li", {
+            children: (0, utils_1.create)("div", {
+                children: [createRows({ schema: schema.items })],
+            }),
+        });
+    }
+    // primitive
+    return (0, utils_1.create)("li", {
+        children: (0, utils_1.create)("div", {
+            children: [
+                (0, utils_1.create)("span", {
+                    style: { opacity: "0.6" },
+                    children: ` ${schema.type}`,
+                }),
+                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema), (message) => (0, utils_1.create)("div", {
+                    style: { marginTop: "var(--ifm-table-cell-padding)" },
+                    children: (0, createDescription_1.createDescription)(message),
+                })),
+                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                    style: { marginTop: "var(--ifm-table-cell-padding)" },
+                    children: (0, createDescription_1.createDescription)(description),
+                })),
+            ],
+        }),
+    });
+}
+function createSchemaDetails({ title, body, ...rest }) {
+    if (body === undefined ||
+        body.content === undefined ||
+        Object.keys(body).length === 0 ||
+        Object.keys(body.content).length === 0) {
+        return undefined;
+    }
+    // TODO:
+    // NOTE: We just pick a random content-type.
+    // How common is it to have multiple?
+    const randomFirstKey = Object.keys(body.content)[0];
+    const firstBody = body.content[randomFirstKey].schema;
+    if (firstBody === undefined) {
+        return undefined;
+    }
+    // we don't show the table if there is no properties to show
+    if (firstBody.properties !== undefined) {
+        if (Object.keys(firstBody.properties).length === 0) {
+            return undefined;
+        }
+    }
+    return (0, createDetails_1.createDetails)({
+        ...rest,
+        children: [
+            (0, createDetailsSummary_1.createDetailsSummary)({
+                style: { textAlign: "left" },
+                children: [
+                    (0, utils_1.create)("strong", { children: `${title}` }),
+                    (0, utils_1.guard)(body.required, () => [
+                        (0, utils_1.create)("strong", {
+                            style: {
+                                fontSize: "var(--ifm-code-font-size)",
+                                color: "var(--openapi-required)",
+                            },
+                            children: " required",
+                        }),
+                    ]),
+                ],
+            }),
+            (0, utils_1.create)("div", {
+                style: { textAlign: "left", marginLeft: "1rem" },
+                children: [
+                    (0, utils_1.guard)(body.description, () => [
+                        (0, utils_1.create)("div", {
+                            style: { marginTop: "1rem", marginBottom: "1rem" },
+                            children: (0, createDescription_1.createDescription)(body.description),
+                        }),
+                    ]),
+                ],
+            }),
+            (0, utils_1.create)("ul", {
+                style: { marginLeft: "1rem" },
+                children: createRowsRoot({ schema: firstBody }),
+            }),
+        ],
+    });
+}
+exports.createSchemaDetails = createSchemaDetails;

package/lib/markdown/createStatusCodes.d.ts

@@ -0,0 +1,6 @@
+import { ApiItem } from "../types";
+interface Props {
+    responses: ApiItem["responses"];
+}
+export declare function createStatusCodes({ responses }: Props): string | undefined;
+export {};

package/lib/markdown/createStatusCodes.js

@@ -0,0 +1,47 @@
+"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.createStatusCodes = void 0;
+const createDescription_1 = require("./createDescription");
+const createSchemaDetails_1 = require("./createSchemaDetails");
+const utils_1 = require("./utils");
+function createStatusCodes({ responses }) {
+    if (responses === undefined) {
+        return undefined;
+    }
+    const codes = Object.keys(responses);
+    if (codes.length === 0) {
+        return undefined;
+    }
+    return (0, utils_1.create)("div", {
+        children: [
+            (0, utils_1.create)("ApiTabs", {
+                children: codes.map((code) => {
+                    return (0, utils_1.create)("TabItem", {
+                        label: code,
+                        value: code,
+                        children: [
+                            (0, utils_1.create)("div", {
+                                children: (0, createDescription_1.createDescription)(responses[code].description),
+                            }),
+                            (0, utils_1.create)("div", {
+                                children: (0, createSchemaDetails_1.createSchemaDetails)({
+                                    title: "Schema",
+                                    body: {
+                                        content: responses[code].content,
+                                    },
+                                }),
+                            }),
+                        ],
+                    });
+                }),
+            }),
+        ],
+    });
+}
+exports.createStatusCodes = createStatusCodes;

package/lib/markdown/createTermsOfService.d.ts

@@ -0,0 +1 @@
+export declare function createTermsOfService(termsOfService: string | undefined): string;

package/lib/markdown/createTermsOfService.js

@@ -0,0 +1,32 @@
+"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.createTermsOfService = void 0;
+const utils_1 = require("./utils");
+function createTermsOfService(termsOfService) {
+    if (!createTermsOfService)
+        return "";
+    return (0, utils_1.create)("div", {
+        style: {
+            marginBottom: "var(--ifm-paragraph-margin-bottom)",
+        },
+        children: [
+            (0, utils_1.create)("h3", {
+                style: {
+                    marginBottom: "0.25rem",
+                },
+                children: "Terms of Service",
+            }),
+            (0, utils_1.create)("a", {
+                href: `${termsOfService}`,
+                children: termsOfService,
+            }),
+        ],
+    });
+}
+exports.createTermsOfService = createTermsOfService;

package/lib/markdown/createVersionBadge.d.ts

@@ -0,0 +1 @@
+export declare function createVersionBadge(version: string | undefined): string;

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, contact, license, termsOfService }, }: InfoPageMetadata): string;

package/lib/markdown/index.js

@@ -0,0 +1,49 @@
+"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 createContactInfo_1 = require("./createContactInfo");
+const createDeprecationNotice_1 = require("./createDeprecationNotice");
+const createDescription_1 = require("./createDescription");
+const createLicense_1 = require("./createLicense");
+const createParamsDetails_1 = require("./createParamsDetails");
+const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
+const createStatusCodes_1 = require("./createStatusCodes");
+const createTermsOfService_1 = require("./createTermsOfService");
+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 ApiTabs from "@theme/ApiTabs";\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, contact, license, termsOfService }, }) {
+    return (0, utils_1.render)([
+        (0, createVersionBadge_1.createVersionBadge)(version),
+        `# ${(0, lodash_1.escape)(title)}\n\n`,
+        (0, createDescription_1.createDescription)(description),
+        (0, createContactInfo_1.createContactInfo)(contact),
+        (0, createTermsOfService_1.createTermsOfService)(termsOfService),
+        (0, createLicense_1.createLicense)(license),
+    ]);
+}
+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 {};