docusaurus-plugin-openapi-docs 1.0.0

package/lib/markdown/createParamsTable.js

@@ -0,0 +1,80 @@
+"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.createParamsTable = void 0;
+const lodash_1 = require("lodash");
+const createDescription_1 = require("./createDescription");
+const createFullWidthTable_1 = require("./createFullWidthTable");
+const schema_1 = require("./schema");
+const utils_1 = require("./utils");
+function createParamsTable({ parameters, type }) {
+    if (parameters === undefined) {
+        return undefined;
+    }
+    const params = parameters.filter((param) => (param === null || param === void 0 ? void 0 : param.in) === type);
+    if (params.length === 0) {
+        return undefined;
+    }
+    return (0, createFullWidthTable_1.createFullWidthTable)({
+        children: [
+            (0, utils_1.create)("thead", {
+                children: (0, utils_1.create)("tr", {
+                    children: (0, utils_1.create)("th", {
+                        style: { textAlign: "left" },
+                        children: `${type.charAt(0).toUpperCase() + type.slice(1)} Parameters`,
+                    }),
+                }),
+            }),
+            (0, utils_1.create)("tbody", {
+                children: params.map((param) => (0, utils_1.create)("tr", {
+                    children: (0, utils_1.create)("td", {
+                        children: [
+                            (0, utils_1.create)("code", { children: param.name }),
+                            (0, utils_1.guard)(param.schema, (schema) => (0, utils_1.create)("span", {
+                                style: { opacity: "0.6" },
+                                children: ` ${(0, schema_1.getSchemaName)(schema)}`,
+                            })),
+                            (0, utils_1.guard)(param.required, () => [
+                                (0, utils_1.create)("span", {
+                                    style: { opacity: "0.6" },
+                                    children: " — ",
+                                }),
+                                (0, utils_1.create)("strong", {
+                                    style: {
+                                        fontSize: "var(--ifm-code-font-size)",
+                                        color: "var(--openapi-required)",
+                                    },
+                                    children: " REQUIRED",
+                                }),
+                            ]),
+                            (0, utils_1.guard)((0, schema_1.getQualifierMessage)(param.schema), (message) => (0, utils_1.create)("div", {
+                                style: { marginTop: "var(--ifm-table-cell-padding)" },
+                                children: (0, createDescription_1.createDescription)(message),
+                            })),
+                            (0, utils_1.guard)(param.description, (description) => (0, utils_1.create)("div", {
+                                style: { marginTop: "var(--ifm-table-cell-padding)" },
+                                children: (0, createDescription_1.createDescription)(description),
+                            })),
+                            (0, utils_1.guard)(param.example, (example) => (0, utils_1.create)("div", {
+                                style: { marginTop: "var(--ifm-table-cell-padding)" },
+                                children: (0, lodash_1.escape)(`Example: ${example}`),
+                            })),
+                            (0, utils_1.guard)(param.examples, (examples) => (0, utils_1.create)("div", {
+                                style: { marginTop: "var(--ifm-table-cell-padding)" },
+                                children: Object.entries(examples).map(([k, v]) => (0, utils_1.create)("div", {
+                                    children: (0, lodash_1.escape)(`Example (${k}): ${v.value}`),
+                                })),
+                            })),
+                        ],
+                    }),
+                })),
+            }),
+        ],
+    });
+}
+exports.createParamsTable = createParamsTable;

package/lib/markdown/createRequestBodyDetails.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    title: string;
+    body: any;
+}
+export declare function createRequestBodyDetails({ title, body }: Props): string | undefined;
+export {};

package/lib/markdown/createRequestBodyDetails.js

@@ -0,0 +1,14 @@
+"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.createRequestBodyDetails = void 0;
+const createSchemaDetails_1 = require("./createSchemaDetails");
+function createRequestBodyDetails({ title, body }) {
+    return (0, createSchemaDetails_1.createSchemaDetails)({ title, body });
+}
+exports.createRequestBodyDetails = createRequestBodyDetails;

package/lib/markdown/createRequestBodyTable.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    title: string;
+    body: any;
+}
+export declare function createRequestBodyTable({ title, body }: Props): string | undefined;
+export {};

package/lib/markdown/createRequestBodyTable.js

@@ -0,0 +1,14 @@
+"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.createRequestBodyTable = void 0;
+const createSchemaTable_1 = require("./createSchemaTable");
+function createRequestBodyTable({ title, body }) {
+    return (0, createSchemaTable_1.createSchemaTable)({ title, body });
+}
+exports.createRequestBodyTable = createRequestBodyTable;

package/lib/markdown/createSchemaDetails.d.ts

@@ -0,0 +1,14 @@
+import { MediaTypeObject } from "../openapi/types";
+interface Props {
+    style?: any;
+    title: string;
+    body: {
+        content?: {
+            [key: string]: MediaTypeObject;
+        };
+        description?: string;
+        required?: boolean;
+    };
+}
+export declare function createSchemaDetails({ title, body, ...rest }: Props): string | undefined;
+export {};

package/lib/markdown/createSchemaDetails.js

@@ -0,0 +1,241 @@
+"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) {
+        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/createSchemaTable.d.ts

@@ -0,0 +1,14 @@
+import { MediaTypeObject } from "../openapi/types";
+interface Props {
+    style?: any;
+    title: string;
+    body: {
+        content?: {
+            [key: string]: MediaTypeObject;
+        };
+        description?: string;
+        required?: boolean;
+    };
+}
+export declare function createSchemaTable({ title, body, ...rest }: Props): string | undefined;
+export {};

package/lib/markdown/createSchemaTable.js

@@ -0,0 +1,217 @@
+"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.createSchemaTable = void 0;
+const createDescription_1 = require("./createDescription");
+const createFullWidthTable_1 = require("./createFullWidthTable");
+const schema_1 = require("./schema");
+const utils_1 = require("./utils");
+function resolveAllOf(allOf) {
+    // TODO: naive implementation (only supports objects, no directly nested allOf)
+    const properties = allOf.reduce((acc, cur) => {
+        if (cur.properties !== undefined) {
+            const next = { ...acc, ...cur.properties };
+            return next;
+        }
+        return acc;
+    }, {});
+    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 }) {
+    return (0, utils_1.create)("tr", {
+        children: (0, utils_1.create)("td", {
+            children: [
+                (0, utils_1.create)("code", { children: name }),
+                (0, utils_1.create)("span", {
+                    style: { opacity: "0.6" },
+                    children: ` ${(0, schema_1.getSchemaName)(schema, true)}`,
+                }),
+                (0, utils_1.guard)(required, () => [
+                    (0, utils_1.create)("span", {
+                        style: { opacity: "0.6" },
+                        children: " — ",
+                    }),
+                    (0, utils_1.create)("strong", {
+                        style: {
+                            fontSize: "var(--ifm-code-font-size)",
+                            color: "var(--openapi-required)",
+                        },
+                        children: " REQUIRED",
+                    }),
+                ]),
+                (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),
+                })),
+                createRows({ schema: schema }),
+            ],
+        }),
+    });
+}
+function createRows({ schema }) {
+    // object
+    if (schema.properties !== undefined) {
+        return (0, createFullWidthTable_1.createFullWidthTable)({
+            style: {
+                marginTop: "var(--ifm-table-cell-padding)",
+                marginBottom: "0px",
+            },
+            children: (0, utils_1.create)("tbody", {
+                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, createFullWidthTable_1.createFullWidthTable)({
+            style: {
+                marginTop: "var(--ifm-table-cell-padding)",
+                marginBottom: "0px",
+            },
+            children: (0, utils_1.create)("tbody", {
+                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)("tr", {
+            children: (0, utils_1.create)("td", {
+                children: [
+                    (0, utils_1.create)("span", {
+                        style: { opacity: "0.6" },
+                        children: ` ${(0, schema_1.getSchemaName)(schema, true)}`,
+                    }),
+                    createRows({ schema: schema.items }),
+                ],
+            }),
+        });
+    }
+    // primitive
+    return (0, utils_1.create)("tr", {
+        children: (0, utils_1.create)("td", {
+            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 createSchemaTable({ title, body, ...rest }) {
+    if (body === undefined || body.content === undefined) {
+        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, createFullWidthTable_1.createFullWidthTable)({
+        ...rest,
+        children: [
+            (0, utils_1.create)("thead", {
+                children: (0, utils_1.create)("tr", {
+                    children: (0, utils_1.create)("th", {
+                        style: { textAlign: "left" },
+                        children: [
+                            `${title} `,
+                            (0, utils_1.guard)(body.required, () => [
+                                (0, utils_1.create)("span", {
+                                    style: { opacity: "0.6" },
+                                    children: " — ",
+                                }),
+                                (0, utils_1.create)("strong", {
+                                    style: {
+                                        fontSize: "var(--ifm-code-font-size)",
+                                        color: "var(--openapi-required)",
+                                    },
+                                    children: " REQUIRED",
+                                }),
+                            ]),
+                            (0, utils_1.create)("div", {
+                                children: (0, createDescription_1.createDescription)(body.description),
+                            }),
+                        ],
+                    }),
+                }),
+            }),
+            (0, utils_1.create)("tbody", {
+                children: createRowsRoot({ schema: firstBody }),
+            }),
+        ],
+    });
+}
+exports.createSchemaTable = createSchemaTable;

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)("Tabs", {
+                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/createVersionBadge.d.ts

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