@necessarylion/adonis-autoswagger 0.0.4 → 0.0.5

package/dist/parsers/comment_parser.js

@@ -0,0 +1,417 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommentParser = void 0;
+const http_status_code_1 = __importDefault(require("http-status-code"));
+const helpers_1 = require("./helpers");
+const util_1 = __importDefault(require("util"));
+const extract_comments_1 = __importDefault(require("extract-comments"));
+const fs_1 = __importDefault(require("fs"));
+const lodash_1 = __importDefault(require("lodash"));
+class CommentParser {
+    parsedFiles = {};
+    exampleGenerator;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    #parseAnnotations(lines) {
+        let summary = "";
+        let tag = "";
+        let description = "";
+        let operationId;
+        let responses = {};
+        let requestBody;
+        let parameters = {};
+        let headers = {};
+        lines.forEach((line) => {
+            if (line.startsWith("@summary")) {
+                summary = line.replace("@summary ", "");
+            }
+            if (line.startsWith("@tag")) {
+                tag = line.replace("@tag ", "");
+            }
+            if (line.startsWith("@description")) {
+                description = line.replace("@description ", "");
+            }
+            if (line.startsWith("@operationId")) {
+                operationId = line.replace("@operationId ", "");
+            }
+            if (line.startsWith("@responseBody")) {
+                responses = {
+                    ...responses,
+                    ...this.#parseResponseBody(line),
+                };
+            }
+            if (line.startsWith("@responseHeader")) {
+                const header = this.#parseResponseHeader(line);
+                if (header === null) {
+                    console.error("Error with line: " + line);
+                    return;
+                }
+                headers[header["status"]] = {
+                    ...headers[header["status"]],
+                    ...header["header"],
+                };
+            }
+            if (line.startsWith("@requestBody")) {
+                requestBody = this.#parseBody(line, "requestBody");
+            }
+            if (line.startsWith("@requestFormDataBody")) {
+                const parsedBody = this.#parseRequestFormDataBody(line);
+                if (parsedBody) {
+                    requestBody = parsedBody;
+                }
+            }
+            if (line.startsWith("@param")) {
+                parameters = { ...parameters, ...this.#parseParam(line) };
+            }
+        });
+        for (const [key, value] of Object.entries(responses)) {
+            if (typeof headers[key] !== undefined) {
+                responses[key]["headers"] = headers[key];
+            }
+            if (!responses[key]["description"]) {
+                responses[key]["description"] = `Returns **${key}** (${http_status_code_1.default.getMessage(key)}) as **${Object.entries(responses[key]["content"])[0][0]}**`;
+            }
+        }
+        return {
+            description,
+            responses,
+            requestBody,
+            parameters,
+            summary,
+            operationId,
+            tag,
+        };
+    }
+    #parseParam(line) {
+        let where = "path";
+        let required = true;
+        let type = "string";
+        let example = null;
+        let enums = [];
+        if (line.startsWith("@paramUse")) {
+            let use = (0, helpers_1.getBetweenBrackets)(line, "paramUse");
+            const used = use.split(",");
+            let h = [];
+            used.forEach((u) => {
+                if (typeof this.options.common.parameters[u] === "undefined") {
+                    return;
+                }
+                const common = this.options.common.parameters[u];
+                h = [...h, ...common];
+            });
+            return h;
+        }
+        if (line.startsWith("@paramPath")) {
+            required = true;
+        }
+        if (line.startsWith("@paramQuery")) {
+            required = false;
+        }
+        let match = line.match("@param([a-zA-Z]*)");
+        if (match !== null) {
+            where = match[1].toLowerCase();
+            line = line.replace(match[0] + " ", "");
+        }
+        let [param, description, meta] = line.split(" - ");
+        if (typeof param === "undefined") {
+            return;
+        }
+        if (typeof description === "undefined") {
+            description = "";
+        }
+        if (typeof meta !== "undefined") {
+            if (meta.includes("@required")) {
+                required = true;
+            }
+            let enumsFromMeta = (0, helpers_1.getBetweenBrackets)(meta, "enum");
+            example = (0, helpers_1.getBetweenBrackets)(meta, "example");
+            const typeFromMeta = (0, helpers_1.getBetweenBrackets)(meta, "type");
+            if (typeFromMeta !== "") {
+                type = typeFromMeta;
+            }
+            if (enumsFromMeta !== "") {
+                enums = enumsFromMeta.split(",");
+                example = enums[0];
+            }
+        }
+        let parameter = {
+            in: where,
+            name: param,
+            description: description,
+            schema: {
+                example: example,
+                type: type,
+            },
+            required: required,
+        };
+        if (enums.length > 1) {
+            parameter["schema"]["enum"] = enums;
+        }
+        return { [param]: parameter };
+    }
+    #parseResponseHeader(responseLine) {
+        let description = "";
+        let example = "";
+        let type = "string";
+        let enums = [];
+        const line = responseLine.replace("@responseHeader ", "");
+        let [status, name, descriptionFromLine, meta] = line.split(" - ");
+        if (typeof status === "undefined" || typeof name === "undefined") {
+            return null;
+        }
+        if (typeof descriptionFromLine !== "undefined") {
+            description = descriptionFromLine;
+        }
+        if (name.includes("@use")) {
+            let use = (0, helpers_1.getBetweenBrackets)(name, "use");
+            const used = use.split(",");
+            let header = {};
+            used.forEach((u) => {
+                if (typeof this.options.common.headers[u] === "undefined") {
+                    return;
+                }
+                const common = this.options.common.headers[u];
+                header = { ...header, ...common };
+            });
+            return {
+                status: status,
+                header: header,
+            };
+        }
+        if (typeof meta !== "undefined") {
+            example = (0, helpers_1.getBetweenBrackets)(meta, "example");
+            const typeFromMeta = (0, helpers_1.getBetweenBrackets)(meta, "type");
+            if (typeFromMeta !== "") {
+                type = typeFromMeta;
+            }
+        }
+        if (example === "" || example === null) {
+            switch (type) {
+                case "string":
+                    example = "string";
+                    break;
+                case "integer":
+                    example = 1;
+                    break;
+                case "float":
+                    example = 1.5;
+                    break;
+            }
+        }
+        let header = {
+            schema: { type: type, example: example },
+            description: description,
+        };
+        if (enums.length > 1) {
+            header["schema"]["enum"] = enums;
+        }
+        return {
+            status: status,
+            header: {
+                [name]: header,
+            },
+        };
+    }
+    #parseResponseBody(responseLine) {
+        let responses = {};
+        const line = responseLine.replace("@responseBody ", "");
+        let [status, res, description] = line.split(" - ");
+        if (typeof status === "undefined")
+            return;
+        responses[status] = this.#parseBody(res, "responseBody");
+        responses[status]["description"] = description;
+        return responses;
+    }
+    #parseRequestFormDataBody(rawLine) {
+        const line = rawLine.replace("@requestFormDataBody ", "");
+        let json = {}, required = [];
+        const isJson = (0, helpers_1.isJSONString)(line);
+        if (!isJson) {
+            // try to get json from reference
+            let rawRef = line.substring(line.indexOf("<") + 1, line.lastIndexOf(">"));
+            const cleandRef = rawRef.replace("[]", "");
+            if (cleandRef === "") {
+                return;
+            }
+            const parsedRef = this.exampleGenerator.parseRef(line, true);
+            let props = [];
+            const ref = this.exampleGenerator.schemas[cleandRef];
+            const ks = [];
+            if (ref.required && Array.isArray(ref.required))
+                required.push(...ref.required);
+            Object.entries(ref.properties).map(([key, value]) => {
+                if (typeof parsedRef[key] === "undefined") {
+                    return;
+                }
+                ks.push(key);
+                if (value["required"])
+                    required.push(key);
+                props.push({
+                    [key]: {
+                        type: typeof value["type"] === "undefined" ? "string" : value["type"],
+                        format: typeof value["format"] === "undefined"
+                            ? "string"
+                            : value["format"],
+                    },
+                });
+            });
+            const properties = props.reduce((acc, curr) => ({ ...acc, ...curr }), {});
+            const appends = Object.keys(parsedRef).filter((k) => !ks.includes(k));
+            json = properties;
+            if (appends.length > 0) {
+                appends.forEach((append) => {
+                    json[append] = parsedRef[append];
+                });
+            }
+        }
+        else {
+            json = JSON.parse(line);
+            for (let key in json) {
+                if (json[key].required === "true") {
+                    required.push(key);
+                }
+            }
+        }
+        // No need to try/catch this JSON.parse as we already did that in the isJSONString function
+        return {
+            content: {
+                "multipart/form-data": {
+                    schema: {
+                        type: "object",
+                        properties: json,
+                        required,
+                    },
+                },
+            },
+        };
+    }
+    #parseBody(rawLine, type) {
+        let line = rawLine.replace(`@${type} `, "");
+        const isJson = (0, helpers_1.isJSONString)(line);
+        if (isJson) {
+            // No need to try/catch this JSON.parse as we already did that in the isJSONString function
+            const json = JSON.parse(line);
+            const obj = this.#jsonToObj(json);
+            return {
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: Array.isArray(json) ? "array" : "object",
+                            ...(Array.isArray(json)
+                                ? { items: this.#arrayItems(json) }
+                                : obj),
+                        },
+                        example: this.exampleGenerator.jsonToRef(json),
+                    },
+                },
+            };
+        }
+        return this.exampleGenerator.parseRef(line);
+    }
+    #arrayItems(json) {
+        const oneOf = [];
+        const type = typeof json[0];
+        if (type === "string") {
+            json.forEach((item) => {
+                const value = this.exampleGenerator.parseRef(item);
+                if (lodash_1.default.has(value, "content.application/json.schema.$ref")) {
+                    oneOf.push({
+                        $ref: value["content"]["application/json"]["schema"]["$ref"],
+                    });
+                }
+            });
+        }
+        if (oneOf.length > 0) {
+            return { oneOf: oneOf };
+        }
+        return { type: typeof json[0] };
+    }
+    #jsonToObj(json) {
+        const obj = {
+            type: "object",
+            properties: Object.keys(json)
+                .map((key) => {
+                const type = typeof json[key];
+                const val = json[key];
+                let value = val;
+                if (type === "object") {
+                    value = this.#jsonToObj(json[key]);
+                }
+                if (type === "string" && val.includes("<") && val.includes(">")) {
+                    value = this.exampleGenerator.parseRef(val);
+                    if (val.includes("[]")) {
+                        let ref = "";
+                        if (lodash_1.default.has(value, "content.application/json.schema.$ref")) {
+                            ref = value["content"]["application/json"]["schema"]["$ref"];
+                        }
+                        if (lodash_1.default.has(value, "content.application/json.schema.items.$ref")) {
+                            ref =
+                                value["content"]["application/json"]["schema"]["items"]["$" + "ref"];
+                        }
+                        value = {
+                            type: "array",
+                            items: {
+                                $ref: ref,
+                            },
+                        };
+                    }
+                    else {
+                        value = {
+                            $ref: value["content"]["application/json"]["schema"]["$ref"],
+                        };
+                    }
+                }
+                return {
+                    [key]: value,
+                };
+            })
+                .reduce((acc, curr) => ({ ...acc, ...curr }), {}),
+        };
+        return obj;
+    }
+    async getAnnotations(file, action) {
+        let annotations = {};
+        let newdata = "";
+        if (typeof file === "undefined")
+            return;
+        if (typeof this.parsedFiles[file] !== "undefined") {
+            newdata = this.parsedFiles[file];
+        }
+        else {
+            try {
+                const readFile = util_1.default.promisify(fs_1.default.readFile);
+                const fileContent = await readFile(file, "utf8");
+                for (const line of fileContent.split("\n")) {
+                    const trimmedLine = line.trim();
+                    if (!trimmedLine.startsWith("@")) {
+                        newdata += trimmedLine + "\n";
+                    }
+                }
+                this.parsedFiles[file] = newdata;
+            }
+            catch (e) {
+                console.error("\x1b[31m✗ File not found\x1b[0m", file);
+            }
+        }
+        const comments = (0, extract_comments_1.default)(newdata);
+        if (comments.length > 0) {
+            comments.forEach((comment) => {
+                if (comment.type !== "BlockComment")
+                    return;
+                let lines = comment.value.split("\n").filter((l) => l != "");
+                // fix for decorators
+                if (lines[0].trim() !== "@" + action)
+                    return;
+                lines = lines.filter((l) => l != "");
+                annotations[action] = this.#parseAnnotations(lines);
+            });
+        }
+        return annotations;
+    }
+}
+exports.CommentParser = CommentParser;

package/dist/parsers/enum_parser.d.ts

@@ -0,0 +1,5 @@
+export declare class EnumParser {
+    #private;
+    constructor();
+    parseEnums(fileContent: string): Record<string, any>;
+}

package/dist/parsers/enum_parser.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnumParser = void 0;
+const lodash_1 = require("lodash");
+class EnumParser {
+    constructor() { }
+    parseEnums(fileContent) {
+        const enums = {};
+        const lines = fileContent.split("\n");
+        let currentEnum = null;
+        let description = null;
+        for (const line of lines) {
+            const trimmedLine = line.trim();
+            if (trimmedLine.startsWith("//")) {
+                description = trimmedLine.slice(2).trim();
+                continue;
+            }
+            if (trimmedLine.startsWith("enum") ||
+                trimmedLine.startsWith("export enum")) {
+                const match = trimmedLine.match(/(?:export\s+)?enum\s+(\w+)/);
+                if (match) {
+                    currentEnum = match[1];
+                    enums[currentEnum] = {
+                        type: "string",
+                        enum: [],
+                        properties: {},
+                        description: description || `${(0, lodash_1.startCase)(currentEnum)} enumeration`,
+                    };
+                    description = null;
+                }
+                continue;
+            }
+            if (currentEnum && trimmedLine !== "{" && trimmedLine !== "}") {
+                const [key, value] = trimmedLine.split("=").map((s) => s.trim());
+                if (key) {
+                    const enumValue = value ? this.#parseEnumValue(value) : key;
+                    enums[currentEnum].enum.push(enumValue);
+                }
+            }
+            if (trimmedLine === "}") {
+                currentEnum = null;
+            }
+        }
+        return enums;
+    }
+    #parseEnumValue(value) {
+        // Remove quotes and comma
+        return value.replace(/['",]/g, "").trim();
+    }
+}
+exports.EnumParser = EnumParser;

package/dist/parsers/helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check if a string is a valid JSON
+ * @param str string
+ * @returns
+ */
+export declare function isJSONString(str: string): boolean;
+/**
+ * Get string between brackets
+ * @param value string
+ * @param start string
+ * @returns
+ */
+export declare function getBetweenBrackets(value: string, start: string): string;

package/dist/parsers/helpers.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isJSONString = isJSONString;
+exports.getBetweenBrackets = getBetweenBrackets;
+/**
+ * Check if a string is a valid JSON
+ * @param str string
+ * @returns
+ */
+function isJSONString(str) {
+    try {
+        JSON.parse(str);
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Get string between brackets
+ * @param value string
+ * @param start string
+ * @returns
+ */
+function getBetweenBrackets(value, start) {
+    let match = value.match(new RegExp(start + "\\(([^()]*)\\)", "g"));
+    if (match !== null) {
+        let m = match[0].replace(start + "(", "").replace(")", "");
+        if (start !== "example") {
+            m = m.replace(/ /g, "");
+        }
+        if (start === "paginated") {
+            return "true";
+        }
+        return m;
+    }
+    return "";
+}

package/dist/parsers/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./comment_parser";
+export * from "./route_parser";
+export * from "./model_parser";
+export * from "./validator_parser";
+export * from "./interface_parser";
+export * from "./enum_parser";

package/dist/parsers/index.js

@@ -0,0 +1,22 @@
+"use strict";
+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("./comment_parser"), exports);
+__exportStar(require("./route_parser"), exports);
+__exportStar(require("./model_parser"), exports);
+__exportStar(require("./validator_parser"), exports);
+__exportStar(require("./interface_parser"), exports);
+__exportStar(require("./enum_parser"), exports);

package/dist/parsers/interface_parser.d.ts

@@ -0,0 +1,13 @@
+import ExampleGenerator from "../example";
+export declare class InterfaceParser {
+    #private;
+    exampleGenerator: ExampleGenerator;
+    snakeCase: boolean;
+    schemas: any;
+    constructor(snakeCase: boolean, schemas?: any);
+    objToExample(obj: Record<string, any>): Record<string, any>;
+    parseProps(obj: Record<string, any>): Record<string, any>;
+    getInheritedProperties(baseType: string): any;
+    parseInterfaces(fileContent: string): Record<string, any>;
+    parseType(type: string | any, field: string): any;
+}