@visulima/jsdoc-open-api 3.0.0-alpha.4 → 3.0.0-alpha.5

package/dist/packem_shared/jsDocumentCommentsToOpenApi-eOlxMuMO.mjs

@@ -0,0 +1,328 @@
+import { parse } from 'comment-parser';
+import mergeWith from 'lodash.mergewith';
+import { c as customizer } from './customizer-CoMXMU7a.mjs';
+
+const fixSecurityObject = (thing) => {
+  if (thing.security) {
+    thing.security = Object.keys(thing.security).map((s) => {
+      return {
+        [s]: thing.security[s]
+      };
+    });
+  }
+};
+const primitiveTypes = /* @__PURE__ */ new Set(["array", "boolean", "integer", "number", "object", "string"]);
+const formatMap = {
+  binary: "string",
+  byte: "string",
+  date: "string",
+  "date-time": "string",
+  double: "number",
+  float: "number",
+  int32: "integer",
+  int64: "integer",
+  password: "string"
+};
+const parseDescription = (tag) => {
+  const rawType = tag.type;
+  const isArray = rawType.endsWith("[]");
+  const parsedType = rawType.replace(/\[]$/, "");
+  const isPrimitive = primitiveTypes.has(parsedType);
+  const isFormat = Object.keys(formatMap).includes(parsedType);
+  let defaultValue;
+  if (tag.default) {
+    switch (parsedType) {
+      case "double":
+      case "float":
+      case "number": {
+        defaultValue = Number.parseFloat(tag.default);
+        break;
+      }
+      case "int32":
+      case "int64":
+      case "integer": {
+        defaultValue = Number.parseInt(tag.default, 10);
+        break;
+      }
+      default: {
+        defaultValue = tag.default;
+        break;
+      }
+    }
+  }
+  let rootType;
+  if (isPrimitive) {
+    rootType = { default: defaultValue, type: parsedType };
+  } else if (isFormat) {
+    rootType = {
+      default: defaultValue,
+      format: parsedType,
+      type: formatMap[parsedType]
+    };
+  } else {
+    rootType = { $ref: `#/components/schemas/${parsedType}` };
+  }
+  let schema = isArray ? {
+    items: {
+      ...rootType
+    },
+    type: "array"
+  } : {
+    ...rootType
+  };
+  if (parsedType === "") {
+    schema = void 0;
+  }
+  let description = tag.description.trim().replace(/^- /u, "");
+  if (description === "") {
+    description = void 0;
+  }
+  return {
+    description,
+    name: tag.name,
+    rawType,
+    required: !tag.optional,
+    schema
+  };
+};
+const tagsToObjects = (tags, verbose) => 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 "bodyComponent": {
+      return {
+        requestBody: {
+          $ref: `#/components/requestBodies/${parsedResponse.rawType}`
+        }
+      };
+    }
+    case "bodyContent": {
+      return {
+        requestBody: {
+          content: {
+            [parsedResponse.name.replace(String.raw`*\/*`, "*/*")]: {
+              schema: parsedResponse.schema
+            }
+          }
+        }
+      };
+    }
+    case "bodyDescription": {
+      return { requestBody: { description: nameAndDescription } };
+    }
+    case "bodyExample": {
+      const [contentType, example] = parsedResponse.name.split(".");
+      return {
+        requestBody: {
+          content: {
+            [contentType]: {
+              examples: {
+                [example]: {
+                  $ref: `#/components/examples/${parsedResponse.rawType}`
+                }
+              }
+            }
+          }
+        }
+      };
+    }
+    case "bodyRequired": {
+      return { requestBody: { required: true } };
+    }
+    case "callback": {
+      return {
+        callbacks: {
+          [parsedResponse.name]: {
+            $ref: `#/components/callbacks/${parsedResponse.rawType}`
+          }
+        }
+      };
+    }
+    case "cookieParam":
+    case "headerParam":
+    case "pathParam":
+    case "queryParam": {
+      return {
+        parameters: [
+          {
+            description: parsedResponse.description,
+            in: tag.tag.replace(/Param$/u, ""),
+            name: parsedResponse.name,
+            required: parsedResponse.required,
+            schema: parsedResponse.schema
+          }
+        ]
+      };
+    }
+    case "deprecated": {
+      return { deprecated: true };
+    }
+    case "description":
+    case "operationId":
+    case "summary": {
+      return { [tag.tag]: nameAndDescription };
+    }
+    case "externalDocs": {
+      return {
+        externalDocs: {
+          description: parsedResponse.description,
+          url: parsedResponse.name
+        }
+      };
+    }
+    case "paramComponent": {
+      return {
+        parameters: [{ $ref: `#/components/parameters/${parsedResponse.rawType}` }]
+      };
+    }
+    case "response": {
+      return {
+        responses: {
+          [parsedResponse.name]: {
+            description: parsedResponse.description
+          }
+        }
+      };
+    }
+    case "responseComponent": {
+      return {
+        responses: {
+          [parsedResponse.name]: {
+            $ref: `#/components/responses/${parsedResponse.rawType}`
+          }
+        }
+      };
+    }
+    case "responseContent": {
+      const [status, contentType] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            content: {
+              [contentType]: {
+                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 "responseHeader": {
+      const [status, header] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            headers: {
+              [header]: {
+                description: parsedResponse.description,
+                schema: parsedResponse.schema
+              }
+            }
+          }
+        }
+      };
+    }
+    case "responseHeaderComponent": {
+      const [status, header] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            headers: {
+              [header]: {
+                $ref: `#/components/headers/${parsedResponse.rawType}`
+              }
+            }
+          }
+        }
+      };
+    }
+    case "responseLink": {
+      const [status, link] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            links: {
+              [link]: {
+                $ref: `#/components/links/${parsedResponse.rawType}`
+              }
+            }
+          }
+        }
+      };
+    }
+    case "security": {
+      const [security, scopeItem] = parsedResponse.name.split(".");
+      let scope = [];
+      if (scopeItem) {
+        scope = [scopeItem];
+      }
+      return {
+        security: { [security]: scope }
+      };
+    }
+    case "server": {
+      return {
+        servers: [
+          {
+            description: parsedResponse.description,
+            url: parsedResponse.name
+          }
+        ]
+      };
+    }
+    case "tag": {
+      return { tags: [nameAndDescription] };
+    }
+    default: {
+      return {};
+    }
+  }
+});
+const commentsToOpenApi = (fileContents, verbose) => {
+  const openAPIRegex = /^(GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE) \/.*$/;
+  const jsDocumentComments = parse(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), customizer);
+    fixSecurityObject(result);
+    const [method, path] = comment.description.split(" ");
+    const pathsObject = {
+      [path.trim()]: {
+        [method.toLowerCase().trim()]: {
+          ...result
+        }
+      }
+    };
+    const spec = JSON.parse(JSON.stringify({ paths: pathsObject }));
+    return {
+      loc,
+      spec
+    };
+  });
+};
+
+export { commentsToOpenApi as default };

package/dist/packem_shared/parseFile-BJwu_na4.cjs

@@ -0,0 +1,42 @@
+'use strict';
+
+const node_fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('yaml');
+const yamlLoc = require('./yamlLoc-BLoIYoXs.cjs');
+
+const _interopDefaultCompat = e => e && typeof e === 'object' && 'default' in e ? e.default : e;
+
+const path__default = /*#__PURE__*/_interopDefaultCompat(path);
+const yaml__default = /*#__PURE__*/_interopDefaultCompat(yaml);
+
+const ALLOWED_KEYS = /* @__PURE__ */ new Set(["components", "externalDocs", "info", "openapi", "paths", "security", "servers", "tags"]);
+class ParseError extends Error {
+  filePath;
+}
+const parseFile = (file, commentsToOpenApi, verbose) => {
+  const fileContent = node_fs.readFileSync(file, { encoding: "utf8" });
+  const extension = path__default.extname(file);
+  if (extension === ".yaml" || extension === ".yml") {
+    const spec = yaml__default.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 [{ loc, spec }];
+    }
+    return [];
+  }
+  try {
+    return commentsToOpenApi(fileContent, verbose);
+  } catch (error) {
+    error.filePath = file;
+    throw error;
+  }
+};
+
+module.exports = parseFile;

package/dist/packem_shared/parseFile-Bxis7tbW.mjs

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import yaml from 'yaml';
+import yamlLoc from './yamlLoc-Cmx4vbRt.mjs';
+
+const ALLOWED_KEYS = /* @__PURE__ */ new Set(["components", "externalDocs", "info", "openapi", "paths", "security", "servers", "tags"]);
+class ParseError extends Error {
+  filePath;
+}
+const parseFile = (file, commentsToOpenApi, verbose) => {
+  const fileContent = 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 [{ loc, spec }];
+    }
+    return [];
+  }
+  try {
+    return commentsToOpenApi(fileContent, verbose);
+  } catch (error) {
+    error.filePath = file;
+    throw error;
+  }
+};
+
+export { parseFile as default };

package/dist/packem_shared/swaggerJsDocumentCommentsToOpenApi-Cb5s1J29.mjs

@@ -0,0 +1,130 @@
+import { parse } from 'comment-parser';
+import mergeWith from 'lodash.mergewith';
+import yaml from 'yaml';
+import { c as customizer } from './customizer-CoMXMU7a.mjs';
+
+const mergeDeep = (first, second) => mergeWith({}, first, second, (a, b) => b === null ? a : void 0);
+const hasEmptyProperty = (object) => Object.keys(object).map((key) => object[key]).every((keyObject) => typeof keyObject === "object" && Object.keys(keyObject).every((key) => !(key in keyObject)));
+const isTagPresentInTags = (tag, tags) => tags.some((targetTag) => tag.name === targetTag.name);
+const getSwaggerVersionFromSpec = (tag) => {
+  switch (tag.tag) {
+    case "asyncapi": {
+      return "v4";
+    }
+    case "openapi": {
+      return "v3";
+    }
+    case "swagger": {
+      return "v2";
+    }
+    default: {
+      return "v2";
+    }
+  }
+};
+
+const 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]);
+  }
+};
+
+const specificationTemplate = {
+  v2: ["paths", "definitions", "responses", "parameters", "securityDefinitions"],
+  v3: ["paths", "definitions", "responses", "parameters", "securityDefinitions", "components"],
+  v4: ["components", "channels"]
+};
+const tagsToObjects = (specs, verbose) => specs.map((spec) => {
+  const hasContent = spec.description !== "" || spec.name !== void 0 && (spec.name.startsWith("/") || spec.name.endsWith(":"));
+  if ((spec.tag === "openapi" || spec.tag === "swagger" || spec.tag === "asyncapi") && hasContent) {
+    let yamlContent = spec.description;
+    if (spec.name !== void 0 && (spec.name.startsWith("/") || spec.name.endsWith(":"))) {
+      yamlContent = yamlContent.trim() === "" ? spec.name : `${spec.name}
+${yamlContent}`;
+    }
+    const parsed = yaml.parseDocument(yamlContent);
+    if (parsed.errors.length > 0) {
+      parsed.errors.map((error) => {
+        const newError = error;
+        newError.annotation = yamlContent;
+        return newError;
+      });
+      let errorString = "Error parsing YAML in @openapi spec:";
+      errorString += verbose ? parsed.errors.map(
+        (error) => `${error.toString()}
+Imbedded within:
+\`\`\`
+  ${error.annotation?.replaceAll("\n", "\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) => {
+      organizeSwaggerObject(specification, parsedDocument, property);
+    });
+    return specification;
+  }
+  return {};
+});
+const commentsToOpenApi = (fileContents, verbose) => {
+  const jsDocumentComments = parse(fileContents, { spacing: "preserve" });
+  return jsDocumentComments.map((comment) => {
+    const loc = comment.tags.length + 1;
+    const result = mergeWith({}, ...tagsToObjects(comment.tags, verbose), customizer);
+    ["definitions", "responses", "parameters", "securityDefinitions", "components", "tags"].forEach((property) => {
+      if (result[property] !== void 0 && hasEmptyProperty(result[property])) {
+        delete result[property];
+      }
+    });
+    const spec = JSON.parse(JSON.stringify(result));
+    return {
+      loc,
+      spec
+    };
+  });
+};
+
+export { commentsToOpenApi as default };

package/dist/packem_shared/swaggerJsDocumentCommentsToOpenApi-JFymRz50.cjs

@@ -0,0 +1,137 @@
+'use strict';
+
+const commentParser = require('comment-parser');
+const mergeWith = require('lodash.mergewith');
+const yaml = require('yaml');
+const customizer = require('./customizer-DDFwFqJl.cjs');
+
+const _interopDefaultCompat = e => e && typeof e === 'object' && 'default' in e ? e.default : e;
+
+const mergeWith__default = /*#__PURE__*/_interopDefaultCompat(mergeWith);
+const yaml__default = /*#__PURE__*/_interopDefaultCompat(yaml);
+
+const mergeDeep = (first, second) => mergeWith__default({}, first, second, (a, b) => b === null ? a : void 0);
+const hasEmptyProperty = (object) => Object.keys(object).map((key) => object[key]).every((keyObject) => typeof keyObject === "object" && Object.keys(keyObject).every((key) => !(key in keyObject)));
+const isTagPresentInTags = (tag, tags) => tags.some((targetTag) => tag.name === targetTag.name);
+const getSwaggerVersionFromSpec = (tag) => {
+  switch (tag.tag) {
+    case "asyncapi": {
+      return "v4";
+    }
+    case "openapi": {
+      return "v3";
+    }
+    case "swagger": {
+      return "v2";
+    }
+    default: {
+      return "v2";
+    }
+  }
+};
+
+const 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]);
+  }
+};
+
+const specificationTemplate = {
+  v2: ["paths", "definitions", "responses", "parameters", "securityDefinitions"],
+  v3: ["paths", "definitions", "responses", "parameters", "securityDefinitions", "components"],
+  v4: ["components", "channels"]
+};
+const tagsToObjects = (specs, verbose) => specs.map((spec) => {
+  const hasContent = spec.description !== "" || spec.name !== void 0 && (spec.name.startsWith("/") || spec.name.endsWith(":"));
+  if ((spec.tag === "openapi" || spec.tag === "swagger" || spec.tag === "asyncapi") && hasContent) {
+    let yamlContent = spec.description;
+    if (spec.name !== void 0 && (spec.name.startsWith("/") || spec.name.endsWith(":"))) {
+      yamlContent = yamlContent.trim() === "" ? spec.name : `${spec.name}
+${yamlContent}`;
+    }
+    const parsed = yaml__default.parseDocument(yamlContent);
+    if (parsed.errors.length > 0) {
+      parsed.errors.map((error) => {
+        const newError = error;
+        newError.annotation = yamlContent;
+        return newError;
+      });
+      let errorString = "Error parsing YAML in @openapi spec:";
+      errorString += verbose ? parsed.errors.map(
+        (error) => `${error.toString()}
+Imbedded within:
+\`\`\`
+  ${error.annotation?.replaceAll("\n", "\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) => {
+      organizeSwaggerObject(specification, parsedDocument, property);
+    });
+    return specification;
+  }
+  return {};
+});
+const commentsToOpenApi = (fileContents, verbose) => {
+  const jsDocumentComments = commentParser.parse(fileContents, { spacing: "preserve" });
+  return jsDocumentComments.map((comment) => {
+    const loc = comment.tags.length + 1;
+    const result = mergeWith__default({}, ...tagsToObjects(comment.tags, verbose), customizer.customizer);
+    ["definitions", "responses", "parameters", "securityDefinitions", "components", "tags"].forEach((property) => {
+      if (result[property] !== void 0 && hasEmptyProperty(result[property])) {
+        delete result[property];
+      }
+    });
+    const spec = JSON.parse(JSON.stringify(result));
+    return {
+      loc,
+      spec
+    };
+  });
+};
+
+module.exports = commentsToOpenApi;

package/dist/packem_shared/validate-DZHaKH07.mjs

@@ -0,0 +1,30 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+
+const DEFAULT_EXCLUDE = [
+  "coverage/**",
+  ".github/**",
+  "**/*.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-workspace,pnpm-lock}.yaml",
+  "**/{package,package-lock}.json",
+  "**/yarn.lock",
+  "**/package.json5",
+  "**/.next/**"
+];
+
+const validate = async (spec) => {
+  await SwaggerParser.validate(spec);
+};
+
+export { DEFAULT_EXCLUDE as D, validate as v };