@visulima/jsdoc-open-api 1.0.0

package/dist/index.mjs

@@ -0,0 +1,633 @@
+// src/util/object-merge.ts
+function objectMerge(a, b) {
+  Object.keys(b).forEach((key) => {
+    if (a[key] === void 0) {
+      a[key] = {
+        ...b[key]
+      };
+    } else {
+      Object.keys(b[key]).forEach((subKey) => {
+        a[key][subKey] = {
+          ...a[key][subKey],
+          ...b[key][subKey]
+        };
+      });
+    }
+  });
+}
+var object_merge_default = objectMerge;
+
+// src/spec-builder.ts
+var SpecBuilder = class {
+  constructor(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) {
+    parsedFile.forEach((file) => {
+      const { paths, components, ...rest } = file;
+      object_merge_default(this, {
+        paths,
+        components
+      });
+      Object.entries(rest).forEach(([key, value]) => {
+        this[key] = value;
+      });
+    });
+  }
+};
+var spec_builder_default = SpecBuilder;
+
+// src/parse-file.ts
+import fs from "fs";
+import path from "path";
+import yaml from "yaml";
+
+// src/util/yaml-loc.ts
+function yamlLoc(string) {
+  const split = string.split(/\r\n|\r|\n/);
+  const filtered = split.filter((line) => {
+    if (/^\s*(#\s*.*)?$/.test(line)) {
+      return false;
+    }
+    return line.trim().length > 0;
+  });
+  return filtered.length;
+}
+var yaml_loc_default = yamlLoc;
+
+// src/parse-file.ts
+var ALLOWED_KEYS = /* @__PURE__ */ new Set(["openapi", "info", "servers", "security", "tags", "externalDocs", "components", "paths"]);
+var ParseError = class extends Error {
+};
+var parseFile = (file, commentsToOpenApi3, verbose) => {
+  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 = yaml_loc_default(fileContent);
+      return [{ spec, loc }];
+    }
+    return [];
+  }
+  try {
+    return commentsToOpenApi3(fileContent, verbose);
+  } catch (error) {
+    error.filePath = file;
+    throw error;
+  }
+};
+var parse_file_default = parseFile;
+
+// src/webpack/swagger-compiler-plugin.ts
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { collect } from "@visulima/readdir";
+import _debug from "debug";
+import { exit } from "process";
+
+// src/jsdoc/comments-to-open-api.ts
+import { parse as parseComments } from "comment-parser";
+import mergeWith from "lodash.mergewith";
+
+// src/util/customizer.ts
+var customizer = (objectValue, sourceValue) => {
+  if (Array.isArray(objectValue)) {
+    return [...objectValue, ...sourceValue];
+  }
+  return void 0;
+};
+var customizer_default = customizer;
+
+// src/jsdoc/comments-to-open-api.ts
+function fixSecurityObject(thing) {
+  if (thing.security) {
+    thing.security = Object.keys(thing.security).map((s) => {
+      return {
+        [s]: thing.security[s]
+      };
+    });
+  }
+}
+var primitiveTypes = /* @__PURE__ */ new Set(["integer", "number", "string", "boolean", "object", "array"]);
+var formatMap = {
+  int32: "integer",
+  int64: "integer",
+  float: "number",
+  double: "number",
+  date: "string",
+  "date-time": "string",
+  password: "string",
+  byte: "string",
+  binary: "string"
+};
+function parseDescription(tag) {
+  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 = isArray ? {
+    type: "array",
+    items: {
+      ...rootType
+    }
+  } : {
+    ...rootType
+  };
+  if (parsedType === void 0) {
+    schema = void 0;
+  }
+  let description = tag.description.trim().replace(/^- /, "");
+  if (description === "") {
+    description = void 0;
+  }
+  return {
+    name: tag.name,
+    description,
+    required: !tag.optional,
+    schema,
+    rawType
+  };
+}
+function tagsToObjects(tags, verbose) {
+  return tags.map((tag) => {
+    const parsedResponse = parseDescription(tag);
+    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 = [];
+        if (scopeItem) {
+          scope = [scopeItem];
+        }
+        return {
+          security: { [security]: scope }
+        };
+      }
+      default: {
+        return {};
+      }
+    }
+  });
+}
+var commentsToOpenApi = (fileContents, verbose) => {
+  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) => {
+    const loc = comment.tags.length + 1;
+    const result = mergeWith({}, ...tagsToObjects(comment.tags, verbose), customizer_default);
+    fixSecurityObject(result);
+    const [method, path2] = comment.description.split(" ");
+    const pathsObject = {
+      [path2.trim()]: {
+        [method.toLowerCase().trim()]: {
+          ...result
+        }
+      }
+    };
+    const spec = JSON.parse(JSON.stringify({ paths: pathsObject }));
+    return {
+      spec,
+      loc
+    };
+  });
+};
+var comments_to_open_api_default = commentsToOpenApi;
+
+// src/swagger-jsdoc/comments-to-open-api.ts
+import { parse as parseComments2 } from "comment-parser";
+import mergeWith3 from "lodash.mergewith";
+import yaml2 from "yaml";
+
+// src/swagger-jsdoc/utils.ts
+import mergeWith2 from "lodash.mergewith";
+var mergeDeep = (first, second) => mergeWith2({}, first, second, (a, b) => b === null ? a : void 0);
+var hasEmptyProperty = (object) => Object.keys(object).map((key) => object[key]).every((keyObject) => typeof keyObject === "object" && Object.keys(keyObject).every((key) => !(key in keyObject)));
+var isTagPresentInTags = (tag, tags) => tags.some((targetTag) => tag.name === targetTag.name);
+var getSwaggerVersionFromSpec = (tag) => {
+  switch (tag.tag) {
+    case "openapi": {
+      return "v3";
+    }
+    case "asyncapi": {
+      return "v4";
+    }
+    case "swagger": {
+      return "v2";
+    }
+    default: {
+      return "v2";
+    }
+  }
+};
+
+// src/swagger-jsdoc/organize-swagger-object.ts
+var organizeSwaggerObject = (swaggerObject, annotation, property) => {
+  if (property === "x-webhooks") {
+    swaggerObject[property] = annotation[property];
+  }
+  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) => {
+      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;
+    swaggerObject.security = security;
+  } else if (property.startsWith("/")) {
+    swaggerObject.paths[property] = mergeDeep(swaggerObject.paths[property], annotation[property]);
+  }
+};
+var organize_swagger_object_default = organizeSwaggerObject;
+
+// src/swagger-jsdoc/comments-to-open-api.ts
+var specificationTemplate = {
+  v2: ["paths", "definitions", "responses", "parameters", "securityDefinitions"],
+  v3: ["paths", "definitions", "responses", "parameters", "securityDefinitions", "components"],
+  v4: ["components", "channels"]
+};
+var tagsToObjects2 = (specs, verbose) => specs.map((spec) => {
+  if ((spec.tag === "openapi" || spec.tag === "swagger" || spec.tag === "asyncapi") && spec.description !== "") {
+    const parsed = yaml2.parseDocument(spec.description);
+    if (parsed.errors && parsed.errors.length > 0) {
+      parsed.errors.map((error) => {
+        const newError = error;
+        newError.annotation = spec.description;
+        return newError;
+      });
+      let errorString = "Error parsing YAML in @openapi spec:";
+      errorString += verbose ? parsed.errors.map((error) => {
+        var _a;
+        return `${error.toString()}
+Imbedded within:
+\`\`\`
+  ${(_a = error == null ? void 0 : error.annotation) == null ? void 0 : _a.replace(/\n/g, "\n  ")}
+\`\`\``;
+      }).join("\n") : parsed.errors.map((error) => error.toString()).join("\n");
+      throw new Error(errorString);
+    }
+    const parsedDocument = parsed.toJSON();
+    const specification = {
+      tags: []
+    };
+    specificationTemplate[getSwaggerVersionFromSpec(spec)].forEach((property) => {
+      specification[property] = specification[property] || {};
+    });
+    Object.keys(parsedDocument).forEach((property) => {
+      organize_swagger_object_default(specification, parsedDocument, property);
+    });
+    return specification;
+  }
+  return {};
+});
+var commentsToOpenApi2 = (fileContents, verbose) => {
+  const jsDocumentComments = parseComments2(fileContents, { spacing: "preserve" });
+  return jsDocumentComments.map((comment) => {
+    const loc = comment.tags.length + 1;
+    const result = mergeWith3({}, ...tagsToObjects2(comment.tags, verbose), customizer_default);
+    ["definitions", "responses", "parameters", "securityDefinitions", "components", "tags"].forEach((property) => {
+      if (typeof result[property] !== "undefined" && hasEmptyProperty(result[property])) {
+        delete result[property];
+      }
+    });
+    const spec = JSON.parse(JSON.stringify(result));
+    return {
+      spec,
+      loc
+    };
+  });
+};
+var comments_to_open_api_default2 = commentsToOpenApi2;
+
+// src/webpack/swagger-compiler-plugin.ts
+var debug = _debug("visulima:jsdoc-open-api:swagger-compiler-plugin");
+var SwaggerCompilerPlugin = class {
+  constructor(assetsPath, sources, swaggerDefinition, options) {
+    this.assetsPath = assetsPath;
+    this.swaggerDefinition = swaggerDefinition;
+    this.sources = sources;
+    this.verbose = options.verbose || false;
+    this.ignore = options.ignore || [];
+  }
+  apply(compiler) {
+    compiler.hooks.make.tapAsync("SwaggerCompilerPlugin", async (compilation, callback) => {
+      console.log("Build paused");
+      console.log("switching to swagger build");
+      const spec = new spec_builder_default(this.swaggerDefinition);
+      for await (const dir of this.sources) {
+        const files = await collect(dir, {
+          skip: [...this.ignore, "node_modules/**"]
+        });
+        if (this.verbose) {
+          console.log(`Found ${files.length} files in ${dir}`);
+          console.log(files);
+        }
+        files.forEach((file) => {
+          debug(`Parsing file ${file}`);
+          const parsedJsDocumentFile = parse_file_default(file, comments_to_open_api_default, this.verbose);
+          spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+          const parsedSwaggerJsDocumentFile = parse_file_default(file, comments_to_open_api_default2, this.verbose);
+          spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+        });
+      }
+      try {
+        await SwaggerParser.validate(JSON.parse(JSON.stringify(spec)));
+      } catch (error) {
+        console.error(error.toJSON());
+        exit(1);
+      }
+      compilation.assets[this.assetsPath] = {
+        source() {
+          return JSON.stringify(spec, null, 2);
+        },
+        size() {
+          return Object.keys(spec).length;
+        }
+      };
+      console.log("switching back to normal build");
+      callback();
+    });
+  }
+};
+var swagger_compiler_plugin_default = SwaggerCompilerPlugin;
+export {
+  spec_builder_default as SpecBuilder,
+  swagger_compiler_plugin_default as SwaggerCompilerPlugin,
+  comments_to_open_api_default as jsDocumentCommentsToOpenApi,
+  parse_file_default as parseFile,
+  comments_to_open_api_default2 as swaggerJsDocumentCommentsToOpenApi,
+  yaml_loc_default as yamlLoc
+};
+//# sourceMappingURL=index.mjs.map