azurajs 3.0.2 → 3.0.4

package/dist/core/index.mjs

@@ -181,31 +181,37 @@ var Router = class {
     return path;
   }
   getAllRoutes() {
+    return this.getRouteDocuments().map(({ method, path }) => ({ method, path }));
+  }
+  /**
+   * Todas as rotas com metadados (ex.: OpenAPI) associados ao handler.
+   */
+  getRouteDocuments() {
     const routes = [];
-    for (const [key] of this.staticRoutes) {
+    for (const [key, stored] of this.staticRoutes) {
       const [method, path] = key.split(":", 2);
-      routes.push({ method, path });
+      routes.push({ method, path, meta: stored.meta });
     }
-    this.collectRoutes(this.root, "", routes);
+    this.collectRoutesWithMeta(this.root, "", routes);
     return routes;
   }
-  collectRoutes(node, prefix, routes) {
-    for (const [method] of node.handlers) {
-      routes.push({ method, path: prefix || "/" });
+  collectRoutesWithMeta(node, prefix, routes) {
+    for (const [method, stored] of node.handlers) {
+      routes.push({ method, path: prefix || "/", meta: stored.meta });
     }
     for (const [seg, child] of node.children) {
-      this.collectRoutes(child, `${prefix}/${seg}`, routes);
+      this.collectRoutesWithMeta(child, `${prefix}/${seg}`, routes);
     }
     if (node.paramChild) {
-      this.collectRoutes(
+      this.collectRoutesWithMeta(
         node.paramChild,
         `${prefix}/:${node.paramChild.paramName}`,
         routes
       );
     }
     if (node.wildcardHandler) {
-      for (const [method] of node.wildcardHandler) {
-        routes.push({ method, path: `${prefix}/*` });
+      for (const [method, stored] of node.wildcardHandler) {
+        routes.push({ method, path: `${prefix}/*`, meta: stored.meta });
       }
     }
   }
@@ -613,7 +619,174 @@ function clearCookieHeader(name, options = {}) {
   });
 }
 
+// src/swagger/constants.ts
+var API_TAGS_KEY = "azura:api-tags";
+var METHOD_TAGS_KEY = "azura:swagger-method-tags";
+var API_OPERATION_KEY = "azura:swagger-operation";
+
+// src/swagger/openapi-builder.ts
+function resolveInfo(options) {
+  return options.info ?? {
+    title: "AzuraJS API",
+    version: "1.0.0",
+    description: "Generated OpenAPI specification"
+  };
+}
+function toOpenApiPath(path) {
+  if (path === "/") return "/";
+  const mapped = path.split("/").map((seg) => {
+    if (seg === "*") return "{wildcard}";
+    return seg.startsWith(":") ? `{${seg.slice(1)}}` : seg;
+  }).join("/").replace(/\/{2,}/g, "/");
+  if (mapped.endsWith("/*")) {
+    return mapped.slice(0, -2) + "/{wildcard}";
+  }
+  return mapped;
+}
+function pathParametersFromTemplate(path) {
+  const re = /\{([^}]+)\}/g;
+  const out = [];
+  let m;
+  const seen = /* @__PURE__ */ new Set();
+  while ((m = re.exec(path)) !== null) {
+    const name = m[1];
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out.push({
+      name,
+      in: "path",
+      required: true,
+      schema: { type: "string" }
+    });
+  }
+  return out;
+}
+function defaultResponses(meta) {
+  if (meta?.responses && Object.keys(meta.responses).length > 0) {
+    const out = {};
+    for (const [code, r] of Object.entries(meta.responses)) {
+      out[String(code)] = {
+        description: r.description,
+        ...r.schema ? { content: { "application/json": { schema: r.schema } } } : {}
+      };
+    }
+    return out;
+  }
+  return {
+    "200": {
+      description: "Successful response",
+      content: {
+        "application/json": {
+          schema: { type: "object", additionalProperties: true }
+        }
+      }
+    }
+  };
+}
+function mergeParameters(meta, pathParams) {
+  const fromMeta = meta?.parameters ?? [];
+  const names = new Set(pathParams.map((p) => p.name));
+  const rest = fromMeta.filter((p) => !(p.in === "path" && names.has(p.name)));
+  const mapped = fromMeta.filter((p) => p.in === "path").map((p) => ({
+    name: p.name,
+    in: "path",
+    required: p.required ?? true,
+    description: p.description,
+    schema: p.schema ?? { type: p.type ?? "string" }
+  }));
+  const pathMerged = [...pathParams];
+  for (const m of mapped) {
+    if (!pathMerged.find((x) => x.name === m.name)) pathMerged.push(m);
+  }
+  return [...pathMerged, ...rest.map((p) => mapParameter(p))];
+}
+function mapParameter(p) {
+  const base = {
+    name: p.name,
+    in: p.in,
+    required: p.required ?? (p.in === "path" ? true : false),
+    description: p.description
+  };
+  if (p.in === "body") {
+    return {
+      ...base,
+      content: {
+        "application/json": {
+          schema: p.schema ?? { type: "object" }
+        }
+      }
+    };
+  }
+  return {
+    ...base,
+    schema: p.schema ?? { type: p.type ?? "string" }
+  };
+}
+function operationIdFor(method, oPath) {
+  const slug = oPath.replace(/[/{}\-*]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+  return `${method.toLowerCase()}_${slug || "root"}`;
+}
+function operationForMethod(method, oPath, meta) {
+  const op = {
+    operationId: operationIdFor(method, oPath),
+    summary: meta?.summary ?? `${method} ${oPath}`,
+    ...meta?.description ? { description: meta.description } : {},
+    ...meta?.deprecated ? { deprecated: true } : {},
+    ...meta?.tags?.length ? { tags: meta.tags } : {},
+    ...meta?.security?.length ? { security: meta.security } : {}
+  };
+  if (["POST", "PUT", "PATCH"].includes(method) && !meta?.parameters?.some((x) => x.in === "body")) {
+    op.requestBody = {
+      content: {
+        "application/json": {
+          schema: { type: "object", additionalProperties: true }
+        }
+      },
+      required: false
+    };
+  }
+  op.responses = defaultResponses(meta);
+  return op;
+}
+function buildOpenApiDocument(routes, options) {
+  const info = resolveInfo(options);
+  const prefix = options.pathPrefix ?? "";
+  const paths = {};
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of routes) {
+    const full = prefix + r.path;
+    const oPath = toOpenApiPath(full);
+    const key = `${r.method}:${oPath}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const pathParams = pathParametersFromTemplate(oPath);
+    const op = operationForMethod(r.method, oPath, r.meta);
+    const parameters = mergeParameters(r.meta, pathParams);
+    if (parameters.length) op.parameters = parameters;
+    const methodLc = r.method.toLowerCase();
+    if (!paths[oPath]) paths[oPath] = {};
+    paths[oPath][methodLc] = op;
+  }
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: info.title,
+      version: info.version,
+      ...info.description ? { description: info.description } : {},
+      ...info.contact ? { contact: info.contact } : {},
+      ...info.license ? { license: info.license } : {}
+    },
+    ...options.servers?.length ? { servers: options.servers } : {},
+    paths
+  };
+}
+
 // src/core/server.ts
+function isRouteDocumentMeta(o) {
+  if (!o || typeof o !== "object" || Array.isArray(o)) return false;
+  const x = o;
+  return "summary" in x || "description" in x || "tags" in x || "deprecated" in x || "parameters" in x || "responses" in x || "security" in x || "produces" in x || "consumes" in x;
+}
 var CONTROLLER_META_KEY = "azura:controller";
 var ROUTES_META_KEY = "azura:routes";
 var PARAMS_META_KEY = "azura:params";
@@ -702,9 +875,19 @@ var AzuraServer = class {
     return this;
   }
   route(method, path, handlers) {
-    const routeHandler = handlers[handlers.length - 1];
-    const middlewares = handlers.slice(0, -1);
-    this.router.add(method, path, routeHandler, middlewares);
+    let meta;
+    let list = handlers;
+    const last = list[list.length - 1];
+    if (list.length >= 2 && isRouteDocumentMeta(last)) {
+      meta = last;
+      list = list.slice(0, -1);
+    }
+    if (list.length === 0) {
+      throw new Error(`Route ${method} ${path} requires a handler function`);
+    }
+    const routeHandler = list[list.length - 1];
+    const middlewares = list.slice(0, -1);
+    this.router.add(method, path, routeHandler, middlewares, meta);
     return this;
   }
   register(...controllers) {
@@ -717,6 +900,7 @@ var AzuraServer = class {
     const instance = new Controller();
     const prefix = Reflect.getMetadata?.(CONTROLLER_META_KEY, Controller) ?? "";
     const controllerMiddlewares = Reflect.getMetadata?.("azura:middlewares", Controller) ?? [];
+    const controllerTags = Reflect.getMetadata?.(API_TAGS_KEY, Controller) ?? [];
     const prototype = Controller.prototype;
     const propertyNames = Object.getOwnPropertyNames(prototype).filter(
       (p) => p !== "constructor"
@@ -732,6 +916,14 @@ var AzuraServer = class {
       const paramsMeta = Reflect.getMetadata?.(PARAMS_META_KEY, prototype, propertyKey) ?? [];
       const routeMiddlewares = Reflect.getMetadata?.("azura:middlewares", prototype, propertyKey) ?? [];
       const allMiddlewares = [...controllerMiddlewares, ...routeMiddlewares];
+      const methodTags = Reflect.getMetadata?.(METHOD_TAGS_KEY, prototype, propertyKey) ?? [];
+      const opExtra = Reflect.getMetadata?.(API_OPERATION_KEY, prototype, propertyKey) ?? {};
+      const tagList = [...controllerTags, ...methodTags, ...routeMeta.meta?.tags ?? []];
+      const mergedMeta = (() => {
+        const m = { ...routeMeta.meta, ...opExtra };
+        if (tagList.length) m.tags = tagList;
+        return Object.keys(m).length ? m : void 0;
+      })();
       const handler = async (req, res) => {
         const args = this.resolveParams(paramsMeta, req, res);
         const result = await instance[propertyKey](...args);
@@ -743,7 +935,7 @@ var AzuraServer = class {
           }
         }
       };
-      this.router.add(routeMeta.method, fullPath, handler, allMiddlewares, routeMeta.meta);
+      this.router.add(routeMeta.method, fullPath, handler, allMiddlewares, mergedMeta);
     }
   }
   resolveParams(paramsMeta, req, res) {
@@ -1097,6 +1289,14 @@ var AzuraServer = class {
   getRoutes() {
     return this.router.getAllRoutes();
   }
+  /** Rotas com metadados OpenAPI (para Swagger ou export manual). */
+  getRouteDocuments() {
+    return this.router.getRouteDocuments();
+  }
+  /** Gera documento OpenAPI 3.0 a partir das rotas registadas. */
+  getOpenApiDocument(options = {}) {
+    return buildOpenApiDocument(this.getRouteDocuments(), options);
+  }
 };
 
 export { AzuraServer, Router };