@visulima/jsdoc-open-api 1.0.2 → 1.0.3

package/src/swagger-jsdoc/utils.ts

@@ -0,0 +1,43 @@
+import type { Spec } from "comment-parser";
+import mergeWith from "lodash.mergewith";
+
+/**
+ * A recursive deep-merge that ignores null values when merging.
+ * This returns the merged object and does not mutate.
+ * @param {object} first the first object to get merged
+ * @param {object} second the second object to get merged
+ */
+export const mergeDeep = (first?: object, second?: object) => mergeWith({}, first, second, (a, b) => (b === null ? a : undefined));
+
+/**
+ * Checks if there is any properties of the input object which are an empty object
+ * @param {object} object - the object to check
+ * @returns {boolean}
+ */
+export const hasEmptyProperty = (object: Record<string, any>): boolean => Object.keys(object)
+    .map((key) => object[key])
+    .every((keyObject) => typeof keyObject === "object" && Object.keys(keyObject).every((key) => !(key in keyObject)));
+
+/**
+ * @param {object} tag
+ * @param {array} tags
+ * @returns {boolean}
+ */
+export const isTagPresentInTags = (tag: Spec, tags: Spec[]) => tags.some((targetTag) => tag.name === targetTag.name);
+
+export const getSwaggerVersionFromSpec = (tag: Spec) => {
+    switch (tag.tag) {
+        case "openapi": {
+            return "v3";
+        }
+        case "asyncapi": {
+            return "v4";
+        }
+        case "swagger": {
+            return "v2";
+        }
+        default: {
+            return "v2";
+        }
+    }
+};

package/src/util/customizer.ts

@@ -0,0 +1,9 @@
+const customizer = (objectValue: any, sourceValue: any) => {
+    if (Array.isArray(objectValue)) {
+        return [...objectValue, ...sourceValue];
+    }
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    return undefined;
+};
+
+export default customizer;

package/src/util/load-definition.ts

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+
+import type { BaseDefinition } from "../exported";
+
+function parseFile(file: string): BaseDefinition {
+    const extension = path.extname(file);
+    if (extension !== ".yaml" && extension !== ".yml" && extension !== ".json") {
+        throw new Error("OpenAPI definition path must be YAML or JSON.");
+    }
+
+    const fileContent = fs.readFileSync(file, { encoding: "utf8" });
+
+    if (extension === ".yaml" || extension === ".yml") {
+        return yaml.parse(fileContent);
+    }
+
+    return JSON.parse(fileContent);
+}
+
+export default parseFile;

package/src/util/object-merge.ts

@@ -0,0 +1,20 @@
+function objectMerge<T>(a: T, b: T) {
+    Object.keys(b as object).forEach((key) => {
+        if (a[key as keyof typeof b] === undefined) {
+            // eslint-disable-next-line no-param-reassign
+            a[key as keyof typeof b] = {
+                ...b[key as keyof typeof b],
+            };
+        } else {
+            Object.keys(b[key as keyof typeof b] as object).forEach((subKey) => {
+                // eslint-disable-next-line no-param-reassign
+                (a[key as keyof typeof b] as { [key: string]: object })[subKey] = {
+                    ...(a[key as keyof typeof b] as { [key: string]: object })[subKey],
+                    ...(b[key as keyof typeof b] as { [key: string]: object })[subKey],
+                };
+            });
+        }
+    });
+}
+
+export default objectMerge;

package/src/util/yaml-loc.ts

@@ -0,0 +1,17 @@
+function yamlLoc(string: string): number {
+    // Break string into lines.
+    const split = string.split(/\r\n|\r|\n/);
+
+    const filtered = split.filter((line) => {
+        // Remove comments.
+        if (/^\s*(#\s*.*)?$/.test(line)) {
+            return false;
+        }
+        // Remove empty lines.
+        return line.trim().length > 0;
+    });
+
+    return filtered.length;
+}
+
+export default yamlLoc;

package/src/webpack/swagger-compiler-plugin.ts

@@ -0,0 +1,168 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { collect } from "@visulima/readdir";
+import fs from "node:fs";
+import { dirname } from "node:path";
+import { exit } from "node:process";
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { Compiler } from "webpack";
+
+import type { BaseDefinition } from "../exported";
+import jsDocumentCommentsToOpenApi from "../jsdoc/comments-to-open-api";
+import parseFile from "../parse-file";
+import SpecBuilder from "../spec-builder";
+import swaggerJsDocumentCommentsToOpenApi from "../swagger-jsdoc/comments-to-open-api";
+
+const exclude = [
+    "coverage/**",
+    ".github/**",
+    "packages/*/test{,s}/**",
+    "**/*.d.ts",
+    "test{,s}/**",
+    "test{,-*}.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}",
+    "**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}",
+    "**/__tests__/**",
+    "**/{ava,babel,nyc}.config.{js,cjs,mjs}",
+    "**/jest.config.{js,cjs,mjs,ts}",
+    "**/{karma,rollup,webpack}.config.js",
+    "**/.{eslint,mocha}rc.{js,cjs}",
+    "**/.{travis,yarnrc}.yml",
+    "**/{docker-compose,docker}.yml",
+    "**/.yamllint.{yaml,yml}",
+    "**/node_modules/**",
+    "**/pnpm-lock.yaml",
+    "**/pnpm-workspace.yaml",
+    "**/{package,package-lock}.json",
+    "**/yarn.lock",
+    "**/package.json5",
+    "**/.next/**",
+];
+
+const errorHandler = (error: any) => {
+    if (error) {
+        // eslint-disable-next-line no-console
+        console.error(error);
+        exit(1);
+    }
+};
+
+class SwaggerCompilerPlugin {
+    private readonly swaggerDefinition: BaseDefinition;
+
+    private readonly sources: string[];
+
+    private readonly verbose: boolean;
+
+    private readonly ignore: string | ReadonlyArray<string>;
+
+    assetsPath: string;
+
+    constructor(
+        assetsPath: string,
+        sources: string[],
+        swaggerDefinition: BaseDefinition,
+        options: {
+            verbose?: boolean;
+            ignore?: string | ReadonlyArray<string>;
+        },
+    ) {
+        this.assetsPath = assetsPath;
+        this.swaggerDefinition = swaggerDefinition;
+        this.sources = sources;
+        this.verbose = options.verbose || false;
+        this.ignore = options.ignore || [];
+    }
+
+    apply(compiler: Compiler) {
+        compiler.hooks.make.tapAsync("SwaggerCompilerPlugin", async (_, callback: VoidFunction) => {
+            // eslint-disable-next-line no-console
+            console.log("Build paused, switching to swagger build");
+
+            const spec = new SpecBuilder(this.swaggerDefinition);
+
+            // eslint-disable-next-line no-restricted-syntax,unicorn/prevent-abbreviations
+            for await (const dir of this.sources) {
+                const files = await collect(dir, {
+                    // eslint-disable-next-line @rushstack/security/no-unsafe-regexp
+                    skip: [...this.ignore, ...exclude],
+                    extensions: [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
+                    minimatchOptions: {
+                        match: {
+                            debug: this.verbose,
+                            matchBase: true,
+                        },
+                        skip: {
+                            debug: this.verbose,
+                            matchBase: true,
+                        },
+                    },
+                });
+
+                if (this.verbose) {
+                    // eslint-disable-next-line no-console
+                    console.log(`Found ${files.length} files in ${dir}`);
+                    // eslint-disable-next-line no-console
+                    console.log(files);
+                }
+
+                files.forEach((file) => {
+                    if (this.verbose) {
+                        // eslint-disable-next-line no-console
+                        console.log(`Parsing file ${file}`);
+                    }
+
+                    try {
+                        const parsedJsDocumentFile = parseFile(file, jsDocumentCommentsToOpenApi, this.verbose);
+
+                        spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+
+                        const parsedSwaggerJsDocumentFile = parseFile(file, swaggerJsDocumentCommentsToOpenApi, this.verbose);
+
+                        spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+                    } catch (error) {
+                        // eslint-disable-next-line no-console
+                        console.error(error);
+                        exit(1);
+                    }
+                });
+            }
+
+            try {
+                if (this.verbose) {
+                    // eslint-disable-next-line no-console
+                    console.log("Validating swagger spec");
+                    // eslint-disable-next-line no-console
+                    console.log(JSON.stringify(spec, null, 2));
+                }
+
+                await SwaggerParser.validate(JSON.parse(JSON.stringify(spec)));
+            } catch (error: any) {
+                // eslint-disable-next-line no-console
+                console.error(error.toJSON());
+                exit(1);
+            }
+
+            const { assetsPath } = this;
+
+            fs.mkdir(dirname(assetsPath), { recursive: true }, (error) => {
+                if (error) {
+                    errorHandler(error);
+                }
+
+                fs.writeFile(assetsPath, JSON.stringify(spec, null, 2), errorHandler);
+            });
+
+            // eslint-disable-next-line unicorn/consistent-destructuring
+            if (this.verbose) {
+                // eslint-disable-next-line no-console,unicorn/consistent-destructuring
+                console.log(`Written swagger spec to "${this.assetsPath}" file`);
+            }
+
+            // eslint-disable-next-line no-console
+            console.log("switching back to normal build");
+
+            callback();
+        });
+    }
+}
+
+export default SwaggerCompilerPlugin;