@visulima/jsdoc-open-api 1.0.2 → 1.0.3

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

@@ -0,0 +1,402 @@
+import type { Spec } from "comment-parser";
+import { parse as parseComments } from "comment-parser";
+import mergeWith from "lodash.mergewith";
+
+import { OpenApiObject, PathsObject } from "../exported";
+import customizer from "../util/customizer";
+
+// The security object has a bizare setup...
+function fixSecurityObject(thing: any) {
+    if (thing.security) {
+        // eslint-disable-next-line no-param-reassign
+        thing.security = Object.keys(thing.security).map((s) => {
+            return {
+                [s]: thing.security[s],
+            };
+        });
+    }
+}
+
+const primitiveTypes = new Set(["integer", "number", "string", "boolean", "object", "array"]);
+
+const formatMap: { [key: string]: string } = {
+    int32: "integer",
+    int64: "integer",
+    float: "number",
+    double: "number",
+    date: "string",
+    "date-time": "string",
+    password: "string",
+    byte: "string",
+    binary: "string",
+};
+
+function parseDescription(tag: any) {
+    const rawType = tag.type;
+    const isArray = rawType && rawType.endsWith("[]");
+
+    let parsedType;
+
+    if (rawType) {
+        parsedType = rawType.replace(/\[]$/, "");
+    }
+
+    const isPrimitive = primitiveTypes.has(parsedType);
+    const isFormat = Object.keys(formatMap).includes(parsedType);
+
+    let defaultValue;
+
+    if (tag.default) {
+        switch (parsedType) {
+            case "integer":
+            case "int32":
+            case "int64": {
+                defaultValue = Number.parseInt(tag.default, 10);
+                break;
+            }
+            case "number":
+            case "double":
+            case "float": {
+                defaultValue = Number.parseFloat(tag.default);
+                break;
+            }
+            default: {
+                defaultValue = tag.default;
+                break;
+            }
+        }
+    }
+
+    let rootType;
+
+    if (isPrimitive) {
+        rootType = { type: parsedType, default: defaultValue };
+    } else if (isFormat) {
+        rootType = {
+            type: formatMap[parsedType],
+            format: parsedType,
+            default: defaultValue,
+        };
+    } else {
+        rootType = { $ref: `#/components/schemas/${parsedType}` };
+    }
+
+    let schema: undefined | object = isArray
+        ? {
+            type: "array",
+            items: {
+                ...rootType,
+            },
+        }
+        : {
+            ...rootType,
+        };
+
+    if (parsedType === undefined) {
+        schema = undefined;
+    }
+
+    // remove the optional dash from the description.
+    let description = tag.description.trim().replace(/^- /, "");
+
+    if (description === "") {
+        description = undefined;
+    }
+
+    return {
+        name: tag.name,
+        description,
+        required: !tag.optional,
+        schema,
+        rawType,
+    };
+}
+
+// @ts-ignore
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function tagsToObjects(tags: Spec[], verbose?: boolean) {
+    return tags.map((tag) => {
+        const parsedResponse = parseDescription(tag);
+
+        // Some ops only have a `description`, merge `name` and `description`
+        // for these.
+        let nameAndDescription = "";
+
+        if (parsedResponse.name) {
+            nameAndDescription += parsedResponse.name;
+        }
+
+        if (parsedResponse.description) {
+            nameAndDescription += ` ${parsedResponse.description.trim()}`;
+        }
+
+        switch (tag.tag) {
+            case "operationId":
+            case "summary":
+            case "description": {
+                return { [tag.tag]: nameAndDescription };
+            }
+
+            case "deprecated": {
+                return { deprecated: true };
+            }
+
+            case "externalDocs": {
+                return {
+                    externalDocs: {
+                        url: parsedResponse.name,
+                        description: parsedResponse.description,
+                    },
+                };
+            }
+
+            case "server": {
+                return {
+                    servers: [
+                        {
+                            url: parsedResponse.name,
+                            description: parsedResponse.description,
+                        },
+                    ],
+                };
+            }
+
+            case "tag": {
+                return { tags: [nameAndDescription] };
+            }
+
+            case "cookieParam":
+            case "headerParam":
+            case "queryParam":
+            case "pathParam": {
+                return {
+                    parameters: [
+                        {
+                            name: parsedResponse.name,
+                            in: tag.tag.replace(/Param$/, ""),
+                            description: parsedResponse.description,
+                            required: parsedResponse.required,
+                            schema: parsedResponse.schema,
+                        },
+                    ],
+                };
+            }
+
+            case "bodyContent": {
+                return {
+                    requestBody: {
+                        content: {
+                            [parsedResponse.name.replace("*\\/*", "*/*")]: {
+                                schema: parsedResponse.schema,
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "bodyExample": {
+                const [contentType, example] = parsedResponse.name.split(".");
+                return {
+                    requestBody: {
+                        content: {
+                            [contentType]: {
+                                examples: {
+                                    [example]: {
+                                        $ref: `#/components/examples/${parsedResponse.rawType}`,
+                                    },
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "bodyDescription": {
+                return { requestBody: { description: nameAndDescription } };
+            }
+
+            case "bodyRequired": {
+                return { requestBody: { required: true } };
+            }
+
+            case "response": {
+                return {
+                    responses: {
+                        [parsedResponse.name]: {
+                            description: parsedResponse.description,
+                        },
+                    },
+                };
+            }
+
+            case "callback": {
+                return {
+                    callbacks: {
+                        [parsedResponse.name]: {
+                            $ref: `#/components/callbacks/${parsedResponse.rawType}`,
+                        },
+                    },
+                };
+            }
+
+            case "responseContent": {
+                const [status, contentType] = parsedResponse.name.split(".");
+
+                return {
+                    responses: {
+                        [status]: {
+                            content: {
+                                [contentType]: {
+                                    schema: parsedResponse.schema,
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "responseHeaderComponent": {
+                const [status, header] = parsedResponse.name.split(".");
+                return {
+                    responses: {
+                        [status]: {
+                            headers: {
+                                [header]: {
+                                    $ref: `#/components/headers/${parsedResponse.rawType}`,
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "responseHeader": {
+                const [status, header] = parsedResponse.name.split(".");
+                return {
+                    responses: {
+                        [status]: {
+                            headers: {
+                                [header]: {
+                                    description: parsedResponse.description,
+                                    schema: parsedResponse.schema,
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "responseExample": {
+                const [status, contentType, example] = parsedResponse.name.split(".");
+                return {
+                    responses: {
+                        [status]: {
+                            content: {
+                                [contentType]: {
+                                    examples: {
+                                        [example]: {
+                                            $ref: `#/components/examples/${parsedResponse.rawType}`,
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "responseLink": {
+                const [status, link] = parsedResponse.name.split(".");
+                return {
+                    responses: {
+                        [status]: {
+                            links: {
+                                [link]: {
+                                    $ref: `#/components/links/${parsedResponse.rawType}`,
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+
+            case "bodyComponent": {
+                return {
+                    requestBody: {
+                        $ref: `#/components/requestBodies/${parsedResponse.rawType}`,
+                    },
+                };
+            }
+
+            case "responseComponent": {
+                return {
+                    responses: {
+                        [parsedResponse.name]: {
+                            $ref: `#/components/responses/${parsedResponse.rawType}`,
+                        },
+                    },
+                };
+            }
+
+            case "paramComponent": {
+                return {
+                    parameters: [{ $ref: `#/components/parameters/${parsedResponse.rawType}` }],
+                };
+            }
+
+            case "security": {
+                const [security, scopeItem] = parsedResponse.name.split(".");
+                let scope: string[] = [];
+                if (scopeItem) {
+                    scope = [scopeItem];
+                }
+                return {
+                    security: { [security]: scope },
+                };
+            }
+
+            default: {
+                return {};
+            }
+        }
+    });
+}
+
+const commentsToOpenApi = (fileContents: string, verbose?: boolean): { spec: OpenApiObject; loc: number }[] => {
+    const openAPIRegex = /^(GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE) \/.*$/;
+
+    const jsDocumentComments = parseComments(fileContents, { spacing: "preserve" });
+
+    return jsDocumentComments
+        .filter((comment) => openAPIRegex.test(comment.description.trim()))
+        .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);
+
+            fixSecurityObject(result);
+
+            const [method, path]: string[] = comment.description.split(" ");
+
+            const pathsObject: PathsObject = {
+                [(path as string).trim()]: {
+                    [(method as string).toLowerCase().trim()]: {
+                        ...result,
+                    },
+                },
+            };
+
+            // Purge all undefined objects/arrays.
+            const spec = JSON.parse(JSON.stringify({ paths: pathsObject }));
+
+            return {
+                spec,
+                loc,
+            };
+        });
+};
+
+export default commentsToOpenApi;

package/src/options.ts

@@ -0,0 +1,28 @@
+const DEFAULT_OPTIONS = {
+    cwd: undefined,
+    extension: [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
+    include: ["**"],
+    exclude: [
+        "coverage/**",
+        "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__/**",
+
+        /* Exclude common development tool configuration files */
+        "**/{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}.yml",
+
+        // always ignore '**/node_modules/**'
+    ],
+    excludeNodeModules: true,
+    verbose: true,
+};
+
+export default DEFAULT_OPTIONS;

package/src/parse-file.ts

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

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

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

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