@visulima/jsdoc-open-api 1.2.0 → 1.2.2

package/src/parse-file.ts

@@ -1,52 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import yaml from "yaml";
-
-import { OpenApiObject } from "./exported";
-import yamlLoc from "./util/yaml-loc";
-
-const ALLOWED_KEYS = new Set(["openapi", "info", "servers", "security", "tags", "externalDocs", "components", "paths"]);
-
-class ParseError extends Error {
-    filePath?: string;
-}
-
-const parseFile = (
-    file: string,
-    commentsToOpenApi: (fileContent: string, verbose?: boolean) => { spec: OpenApiObject; loc: number }[],
-    verbose?: boolean,
-): { spec: OpenApiObject; loc: number }[] => {
-    const fileContent = fs.readFileSync(file, { encoding: "utf8" });
-    const extension = path.extname(file);
-
-    if (extension === ".yaml" || extension === ".yml") {
-        const spec = yaml.parse(fileContent);
-        const invalidKeys = Object.keys(spec).filter((key) => !ALLOWED_KEYS.has(key));
-
-        if (invalidKeys.length > 0) {
-            const error = new ParseError(`Unexpected keys: ${invalidKeys.join(", ")}`);
-
-            error.filePath = file;
-
-            throw error;
-        }
-
-        if (Object.keys(spec).some((key) => ALLOWED_KEYS.has(key))) {
-            const loc = yamlLoc(fileContent);
-
-            return [{ spec, loc }];
-        }
-
-        return [];
-    }
-
-    try {
-        return commentsToOpenApi(fileContent, verbose);
-    } catch (error: any) {
-        error.filePath = file;
-
-        throw error;
-    }
-};
-
-export default parseFile;

package/src/spec-builder.ts

@@ -1,61 +0,0 @@
-import {
-    BaseDefinition,
-    ComponentsObject,
-    ExternalDocumentationObject,
-    InfoObject,
-    OpenApiObject,
-    PathsObject,
-    SecurityRequirementObject,
-    ServerObject,
-    TagObject,
-} from "./exported";
-import objectMerge from "./util/object-merge";
-
-class SpecBuilder implements OpenApiObject {
-    openapi: string;
-
-    info: InfoObject;
-
-    servers?: ServerObject[];
-
-    paths: PathsObject;
-
-    components?: ComponentsObject;
-
-    security?: SecurityRequirementObject[];
-
-    tags?: TagObject[];
-
-    externalDocs?: ExternalDocumentationObject;
-
-    constructor(baseDefinition: BaseDefinition) {
-        this.openapi = baseDefinition.openapi;
-        this.info = baseDefinition.info;
-        this.servers = baseDefinition.servers;
-        this.paths = baseDefinition.paths || {};
-        this.components = baseDefinition.components;
-        this.security = baseDefinition.security;
-        this.tags = baseDefinition.tags;
-        this.externalDocs = baseDefinition.externalDocs;
-    }
-
-    addData(parsedFile: OpenApiObject[]) {
-        parsedFile.forEach((file) => {
-            const { paths, components, ...rest } = file;
-
-            // only merge paths and components
-            objectMerge(this, {
-                paths: paths || {},
-                components: components || {},
-            } as OpenApiObject);
-
-            // overwrite everything else:
-            Object.entries(rest).forEach(([key, value]) => {
-                // @ts-ignore
-                this[key as keyof OpenApiObject] = value;
-            });
-        });
-    }
-}
-
-export default SpecBuilder;

package/src/swagger-jsdoc/comments-to-open-api.ts

@@ -1,89 +0,0 @@
-import type { Spec } from "comment-parser";
-import { parse as parseComments } from "comment-parser";
-import mergeWith from "lodash.mergewith";
-import yaml, { YAMLError } from "yaml";
-
-import { OpenApiObject } from "../exported";
-import customizer from "../util/customizer";
-import organizeSwaggerObject from "./organize-swagger-object";
-import { getSwaggerVersionFromSpec, hasEmptyProperty } from "./utils";
-
-const specificationTemplate = {
-    v2: ["paths", "definitions", "responses", "parameters", "securityDefinitions"],
-    v3: ["paths", "definitions", "responses", "parameters", "securityDefinitions", "components"],
-    v4: ["components", "channels"],
-};
-
-type ExtendedYAMLError = YAMLError & { annotation?: string };
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const tagsToObjects = (specs: Spec[], verbose?: boolean) => specs.map((spec: Spec) => {
-    if ((spec.tag === "openapi" || spec.tag === "swagger" || spec.tag === "asyncapi") && spec.description !== "") {
-        const parsed = yaml.parseDocument(spec.description);
-
-        if (parsed.errors && parsed.errors.length > 0) {
-            parsed.errors.map<ExtendedYAMLError>((error) => {
-                const newError: ExtendedYAMLError = error;
-
-                newError.annotation = spec.description;
-
-                return newError;
-            });
-
-            let errorString = "Error parsing YAML in @openapi spec:";
-
-            errorString += verbose
-                ? (parsed.errors as ExtendedYAMLError[])
-                    .map((error) => `${error.toString()}\nImbedded within:\n\`\`\`\n  ${error?.annotation?.replace(/\n/g, "\n  ")}\n\`\`\``)
-                    .join("\n")
-                : parsed.errors.map((error) => error.toString()).join("\n");
-
-            throw new Error(errorString);
-        }
-
-        const parsedDocument = parsed.toJSON();
-        const specification: Record<string, any> = {
-            tags: [],
-        };
-
-        specificationTemplate[getSwaggerVersionFromSpec(spec)].forEach((property) => {
-            specification[property] = specification[property] || {};
-        });
-
-        Object.keys(parsedDocument).forEach((property) => {
-            organizeSwaggerObject(specification, parsedDocument, property);
-        });
-
-        return specification;
-    }
-
-    return {};
-});
-
-const commentsToOpenApi = (fileContents: string, verbose?: boolean): { spec: OpenApiObject; loc: number }[] => {
-    const jsDocumentComments = parseComments(fileContents, { spacing: "preserve" });
-
-    return jsDocumentComments.map((comment) => {
-        // Line count, number of tags + 1 for description.
-        // - Don't count line-breaking due to long descriptions
-        // - Don't count empty lines
-        const loc = comment.tags.length + 1;
-        const result = mergeWith({}, ...tagsToObjects(comment.tags, verbose), customizer);
-
-        ["definitions", "responses", "parameters", "securityDefinitions", "components", "tags"].forEach((property) => {
-            if (typeof result[property] !== "undefined" && hasEmptyProperty(result[property])) {
-                delete result[property];
-            }
-        });
-
-        // Purge all undefined objects/arrays.
-        const spec = JSON.parse(JSON.stringify(result));
-
-        return {
-            spec,
-            loc,
-        };
-    });
-};
-
-export default commentsToOpenApi;

package/src/swagger-jsdoc/organize-swagger-object.ts

@@ -1,66 +0,0 @@
-import { isTagPresentInTags, mergeDeep } from "./utils";
-
-/**
- * @param {object} swaggerObject
- * @param {object} annotation
- * @param {string} property
- */
-// eslint-disable-next-line radar/no-duplicate-string
-const organizeSwaggerObject = (swaggerObject: Record<string, any>, annotation: Record<string, any>, property: string) => {
-    // Root property on purpose.
-    // eslint-disable-next-line no-secrets/no-secrets
-    // @see https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/002_Webhooks.md#proposed-solution
-    if (property === "x-webhooks") {
-        // eslint-disable-next-line no-param-reassign
-        swaggerObject[property] = annotation[property];
-    }
-
-    // Other extensions can be in varying places depending on different vendors and opinions.
-    // The following return makes it so that they are not put in `paths` in the last case.
-    // New specific extensions will need to be handled on case-by-case if to be included in `paths`.
-    if (property.startsWith("x-")) {
-        return;
-    }
-
-    const commonProperties = [
-        "components",
-        "consumes",
-        "produces",
-        "paths",
-        "schemas",
-        "securityDefinitions",
-        "responses",
-        "parameters",
-        "definitions",
-        "channels",
-    ];
-    if (commonProperties.includes(property)) {
-        Object.keys(annotation[property]).forEach((definition) => {
-            // eslint-disable-next-line no-param-reassign
-            swaggerObject[property][definition] = mergeDeep(swaggerObject[property][definition], annotation[property][definition]);
-        });
-    } else if (property === "tags") {
-        const { tags } = annotation;
-
-        if (Array.isArray(tags)) {
-            tags.forEach((tag) => {
-                if (!isTagPresentInTags(tag, swaggerObject.tags)) {
-                    swaggerObject.tags.push(tag);
-                }
-            });
-        } else if (!isTagPresentInTags(tags, swaggerObject.tags)) {
-            swaggerObject.tags.push(tags);
-        }
-    } else if (property === "security") {
-        const { security } = annotation;
-
-        // eslint-disable-next-line no-param-reassign
-        swaggerObject.security = security;
-    } else if (property.startsWith("/")) {
-        // Paths which are not defined as "paths" property, starting with a slash "/"
-        // eslint-disable-next-line no-param-reassign
-        swaggerObject.paths[property] = mergeDeep(swaggerObject.paths[property], annotation[property]);
-    }
-};
-
-export default organizeSwaggerObject;

package/src/swagger-jsdoc/utils.ts

@@ -1,43 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,169 +0,0 @@
-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"],
-                    includeDirs: false,
-                    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;