azurajs 3.0.3 → 3.0.4

package/README.md

@@ -100,6 +100,38 @@ app.listen(3000);
 | `SSEPlugin` | Server-Sent Events with client management |
 | `ProxyPlugin` | HTTP reverse proxy |
 | `MultipartPlugin` | Multipart file upload parsing |
+| `SwaggerPlugin` | OpenAPI 3 spec + Swagger UI (dark minimal theme, zero extra deps) |
+
+### OpenAPI & Swagger UI
+
+Register `SwaggerPlugin` **before** heavy middleware so `/docs` and `/openapi.json` are served. Use `@ApiTags` / `@ApiOperation` on controllers, or pass a [RouteMeta](src/types/routes.type.ts) object as the last argument to `app.get()` / `app.post()` for imperative routes.
+
+```typescript
+import { AzuraServer, SwaggerPlugin, ApiTags, ApiOperation, Controller, Get } from "azurats";
+
+@Controller("/api")
+class UsersController {
+  @ApiTags("users")
+  @ApiOperation({ summary: "List users" })
+  @Get("/")
+  list() {
+    return { users: [] };
+  }
+}
+
+const app = new AzuraServer();
+app.plugin(
+  SwaggerPlugin({
+    getDocuments: () => app.getRouteDocuments(),
+    info: { title: "My API", version: "1.0.0" },
+  }),
+);
+app.register(UsersController);
+// http://localhost:3000/docs  — Swagger UI
+// http://localhost:3000/openapi.json — raw OpenAPI
+```
+
+If you use `HelmetPlugin` with a strict `Content-Security-Policy`, allow inline scripts for the docs path or register Swagger without CSP on `/docs`.
 
 ### Plugin Usage
 

package/dist/IpResolver-BVgnGnpf.d.mts

@@ -0,0 +1,5 @@
+import { IncomingMessage } from 'node:http';
+
+declare function resolveIp(req: IncomingMessage): string;
+
+export { resolveIp as r };

package/dist/IpResolver-BVgnGnpf.d.ts

@@ -0,0 +1,5 @@
+import { IncomingMessage } from 'node:http';
+
+declare function resolveIp(req: IncomingMessage): string;
+
+export { resolveIp as r };

package/dist/SwaggerPlugin-C0UZTjaZ.d.ts

@@ -0,0 +1,6 @@
+import { g as PluginHandler } from './plugin.type-D4HHceYz.js';
+import { S as SwaggerPluginOptions } from './swagger.type-CfDbFCZC.js';
+
+declare function SwaggerPlugin(options: SwaggerPluginOptions): PluginHandler;
+
+export { SwaggerPlugin as S };

package/dist/SwaggerPlugin-wr9S4SRG.d.mts

@@ -0,0 +1,6 @@
+import { g as PluginHandler } from './plugin.type-BNooWhKa.mjs';
+import { S as SwaggerPluginOptions } from './swagger.type-Bfn5nGR8.mjs';
+
+declare function SwaggerPlugin(options: SwaggerPluginOptions): PluginHandler;
+
+export { SwaggerPlugin as S };

package/dist/cookies/index.d.mts

@@ -0,0 +1,7 @@
+import { C as CookieOptions } from '../common.type-BhGCNyEm.mjs';
+import 'node:http';
+
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+declare function clearCookieHeader(name: string, options?: CookieOptions): string;
+
+export { clearCookieHeader, serializeCookie };

package/dist/cookies/index.d.ts

@@ -0,0 +1,7 @@
+import { C as CookieOptions } from '../common.type-BhGCNyEm.js';
+import 'node:http';
+
+declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+declare function clearCookieHeader(name: string, options?: CookieOptions): string;
+
+export { clearCookieHeader, serializeCookie };

package/dist/cookies/index.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// src/utils/cookies/CookieManager.ts
+function serializeCookie(name, value, options = {}) {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+  if (options.maxAge != null) {
+    cookie += `; Max-Age=${Math.floor(options.maxAge)}`;
+  }
+  if (options.expires) {
+    cookie += `; Expires=${options.expires.toUTCString()}`;
+  }
+  if (options.domain) {
+    cookie += `; Domain=${options.domain}`;
+  }
+  cookie += `; Path=${options.path ?? "/"}`;
+  if (options.secure) {
+    cookie += "; Secure";
+  }
+  if (options.httpOnly !== false) {
+    cookie += "; HttpOnly";
+  }
+  if (options.sameSite) {
+    cookie += `; SameSite=${options.sameSite}`;
+  }
+  return cookie;
+}
+function clearCookieHeader(name, options = {}) {
+  return serializeCookie(name, "", {
+    ...options,
+    maxAge: 0,
+    expires: /* @__PURE__ */ new Date(0)
+  });
+}
+
+exports.clearCookieHeader = clearCookieHeader;
+exports.serializeCookie = serializeCookie;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/cookies/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/cookies/CookieManager.ts"],"names":[],"mappings":";;;AAEO,SAAS,eAAA,CACd,IAAA,EACA,KAAA,EACA,OAAA,GAAyB,EAAC,EAClB;AACR,EAAA,IAAI,MAAA,GAAS,GAAG,kBAAA,CAAmB,IAAI,CAAC,CAAA,CAAA,EAAI,kBAAA,CAAmB,KAAK,CAAC,CAAA,CAAA;AAErE,EAAA,IAAI,OAAA,CAAQ,UAAU,IAAA,EAAM;AAC1B,IAAA,MAAA,IAAU,CAAA,UAAA,EAAa,IAAA,CAAK,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAC,CAAA,CAAA;AAAA,EACnD;AAEA,EAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,IAAA,MAAA,IAAU,CAAA,UAAA,EAAa,OAAA,CAAQ,OAAA,CAAQ,WAAA,EAAa,CAAA,CAAA;AAAA,EACtD;AAEA,EAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,IAAA,MAAA,IAAU,CAAA,SAAA,EAAY,QAAQ,MAAM,CAAA,CAAA;AAAA,EACtC;AAEA,EAAA,MAAA,IAAU,CAAA,OAAA,EAAU,OAAA,CAAQ,IAAA,IAAQ,GAAG,CAAA,CAAA;AAEvC,EAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,IAAA,MAAA,IAAU,UAAA;AAAA,EACZ;AAEA,EAAA,IAAI,OAAA,CAAQ,aAAa,KAAA,EAAO;AAC9B,IAAA,MAAA,IAAU,YAAA;AAAA,EACZ;AAEA,EAAA,IAAI,QAAQ,QAAA,EAAU;AACpB,IAAA,MAAA,IAAU,CAAA,WAAA,EAAc,QAAQ,QAAQ,CAAA,CAAA;AAAA,EAC1C;AAEA,EAAA,OAAO,MAAA;AACT;AAEO,SAAS,iBAAA,CACd,IAAA,EACA,OAAA,GAAyB,EAAC,EAClB;AACR,EAAA,OAAO,eAAA,CAAgB,MAAM,EAAA,EAAI;AAAA,IAC/B,GAAG,OAAA;AAAA,IACH,MAAA,EAAQ,CAAA;AAAA,IACR,OAAA,kBAAS,IAAI,IAAA,CAAK,CAAC;AAAA,GACpB,CAAA;AACH","file":"index.js","sourcesContent":["import type { CookieOptions } from \"../../types/common.type.js\";\r\n\r\nexport function serializeCookie(\r\n  name: string,\r\n  value: string,\r\n  options: CookieOptions = {},\r\n): string {\r\n  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;\r\n\r\n  if (options.maxAge != null) {\r\n    cookie += `; Max-Age=${Math.floor(options.maxAge)}`;\r\n  }\r\n\r\n  if (options.expires) {\r\n    cookie += `; Expires=${options.expires.toUTCString()}`;\r\n  }\r\n\r\n  if (options.domain) {\r\n    cookie += `; Domain=${options.domain}`;\r\n  }\r\n\r\n  cookie += `; Path=${options.path ?? \"/\"}`;\r\n\r\n  if (options.secure) {\r\n    cookie += \"; Secure\";\r\n  }\r\n\r\n  if (options.httpOnly !== false) {\r\n    cookie += \"; HttpOnly\";\r\n  }\r\n\r\n  if (options.sameSite) {\r\n    cookie += `; SameSite=${options.sameSite}`;\r\n  }\r\n\r\n  return cookie;\r\n}\r\n\r\nexport function clearCookieHeader(\r\n  name: string,\r\n  options: CookieOptions = {},\r\n): string {\r\n  return serializeCookie(name, \"\", {\r\n    ...options,\r\n    maxAge: 0,\r\n    expires: new Date(0),\r\n  });\r\n}\r\n"]}

package/dist/cookies/index.mjs

@@ -0,0 +1,35 @@
+// src/utils/cookies/CookieManager.ts
+function serializeCookie(name, value, options = {}) {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+  if (options.maxAge != null) {
+    cookie += `; Max-Age=${Math.floor(options.maxAge)}`;
+  }
+  if (options.expires) {
+    cookie += `; Expires=${options.expires.toUTCString()}`;
+  }
+  if (options.domain) {
+    cookie += `; Domain=${options.domain}`;
+  }
+  cookie += `; Path=${options.path ?? "/"}`;
+  if (options.secure) {
+    cookie += "; Secure";
+  }
+  if (options.httpOnly !== false) {
+    cookie += "; HttpOnly";
+  }
+  if (options.sameSite) {
+    cookie += `; SameSite=${options.sameSite}`;
+  }
+  return cookie;
+}
+function clearCookieHeader(name, options = {}) {
+  return serializeCookie(name, "", {
+    ...options,
+    maxAge: 0,
+    expires: /* @__PURE__ */ new Date(0)
+  });
+}
+
+export { clearCookieHeader, serializeCookie };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/cookies/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/cookies/CookieManager.ts"],"names":[],"mappings":";AAEO,SAAS,eAAA,CACd,IAAA,EACA,KAAA,EACA,OAAA,GAAyB,EAAC,EAClB;AACR,EAAA,IAAI,MAAA,GAAS,GAAG,kBAAA,CAAmB,IAAI,CAAC,CAAA,CAAA,EAAI,kBAAA,CAAmB,KAAK,CAAC,CAAA,CAAA;AAErE,EAAA,IAAI,OAAA,CAAQ,UAAU,IAAA,EAAM;AAC1B,IAAA,MAAA,IAAU,CAAA,UAAA,EAAa,IAAA,CAAK,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAC,CAAA,CAAA;AAAA,EACnD;AAEA,EAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,IAAA,MAAA,IAAU,CAAA,UAAA,EAAa,OAAA,CAAQ,OAAA,CAAQ,WAAA,EAAa,CAAA,CAAA;AAAA,EACtD;AAEA,EAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,IAAA,MAAA,IAAU,CAAA,SAAA,EAAY,QAAQ,MAAM,CAAA,CAAA;AAAA,EACtC;AAEA,EAAA,MAAA,IAAU,CAAA,OAAA,EAAU,OAAA,CAAQ,IAAA,IAAQ,GAAG,CAAA,CAAA;AAEvC,EAAA,IAAI,QAAQ,MAAA,EAAQ;AAClB,IAAA,MAAA,IAAU,UAAA;AAAA,EACZ;AAEA,EAAA,IAAI,OAAA,CAAQ,aAAa,KAAA,EAAO;AAC9B,IAAA,MAAA,IAAU,YAAA;AAAA,EACZ;AAEA,EAAA,IAAI,QAAQ,QAAA,EAAU;AACpB,IAAA,MAAA,IAAU,CAAA,WAAA,EAAc,QAAQ,QAAQ,CAAA,CAAA;AAAA,EAC1C;AAEA,EAAA,OAAO,MAAA;AACT;AAEO,SAAS,iBAAA,CACd,IAAA,EACA,OAAA,GAAyB,EAAC,EAClB;AACR,EAAA,OAAO,eAAA,CAAgB,MAAM,EAAA,EAAI;AAAA,IAC/B,GAAG,OAAA;AAAA,IACH,MAAA,EAAQ,CAAA;AAAA,IACR,OAAA,kBAAS,IAAI,IAAA,CAAK,CAAC;AAAA,GACpB,CAAA;AACH","file":"index.mjs","sourcesContent":["import type { CookieOptions } from \"../../types/common.type.js\";\r\n\r\nexport function serializeCookie(\r\n  name: string,\r\n  value: string,\r\n  options: CookieOptions = {},\r\n): string {\r\n  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;\r\n\r\n  if (options.maxAge != null) {\r\n    cookie += `; Max-Age=${Math.floor(options.maxAge)}`;\r\n  }\r\n\r\n  if (options.expires) {\r\n    cookie += `; Expires=${options.expires.toUTCString()}`;\r\n  }\r\n\r\n  if (options.domain) {\r\n    cookie += `; Domain=${options.domain}`;\r\n  }\r\n\r\n  cookie += `; Path=${options.path ?? \"/\"}`;\r\n\r\n  if (options.secure) {\r\n    cookie += \"; Secure\";\r\n  }\r\n\r\n  if (options.httpOnly !== false) {\r\n    cookie += \"; HttpOnly\";\r\n  }\r\n\r\n  if (options.sameSite) {\r\n    cookie += `; SameSite=${options.sameSite}`;\r\n  }\r\n\r\n  return cookie;\r\n}\r\n\r\nexport function clearCookieHeader(\r\n  name: string,\r\n  options: CookieOptions = {},\r\n): string {\r\n  return serializeCookie(name, \"\", {\r\n    ...options,\r\n    maxAge: 0,\r\n    expires: new Date(0),\r\n  });\r\n}\r\n"]}

package/dist/core/index.d.mts

@@ -1,24 +1,11 @@
+import { R as Router, a as RouteDocument } from '../index-j6QGMhZU.mjs';
 import { Server } from 'node:http';
-import { H as HttpMethod, R as RouteHandler, M as MiddlewareHandler, b as RouteMatch, E as ErrorHandler } from '../common.type-BhGCNyEm.mjs';
 import { Logger } from '../logger/index.mjs';
+import { M as MiddlewareHandler, E as ErrorHandler, H as HttpMethod } from '../common.type-BhGCNyEm.mjs';
 import { A as AzuraConfig } from '../config.type-4K-xcMSy.mjs';
 import { g as PluginHandler } from '../plugin.type-BNooWhKa.mjs';
-
-declare class Router {
-    private root;
-    private cache;
-    private staticRoutes;
-    constructor(cacheSize?: number);
-    add(method: HttpMethod, path: string, handler: RouteHandler, middlewares?: MiddlewareHandler[], meta?: Record<string, any>): void;
-    find(method: HttpMethod, path: string): RouteMatch | null;
-    private matchNode;
-    private normalizePath;
-    getAllRoutes(): Array<{
-        method: HttpMethod;
-        path: string;
-    }>;
-    private collectRoutes;
-}
+import { d as RouteMeta } from '../routes.type-DZO5VBW2.mjs';
+import { B as BuildOpenApiOptions } from '../swagger.type-Bfn5nGR8.mjs';
 
 declare class AzuraServer {
     private server;
@@ -33,14 +20,14 @@ declare class AzuraServer {
     use(handler: MiddlewareHandler | PluginHandler): this;
     plugin(handler: PluginHandler): this;
     onError(handler: ErrorHandler): this;
-    get(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    post(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    put(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    delete(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    patch(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    head(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    options(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    all(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
+    get(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    post(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    put(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    delete(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    patch(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    head(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    options(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    all(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
     private route;
     register(...controllers: (new (...args: any[]) => any)[]): this;
     private registerController;
@@ -60,6 +47,10 @@ declare class AzuraServer {
         method: HttpMethod;
         path: string;
     }>;
+    /** Rotas com metadados OpenAPI (para Swagger ou export manual). */
+    getRouteDocuments(): RouteDocument[];
+    /** Gera documento OpenAPI 3.0 a partir das rotas registadas. */
+    getOpenApiDocument(options?: BuildOpenApiOptions): Record<string, unknown>;
 }
 
-export { AzuraServer, Router };
+export { AzuraServer, RouteDocument, Router };

package/dist/core/index.d.ts

@@ -1,24 +1,11 @@
+import { R as Router, a as RouteDocument } from '../index-tpPZS_UK.js';
 import { Server } from 'node:http';
-import { H as HttpMethod, R as RouteHandler, M as MiddlewareHandler, b as RouteMatch, E as ErrorHandler } from '../common.type-BhGCNyEm.js';
 import { Logger } from '../logger/index.js';
+import { M as MiddlewareHandler, E as ErrorHandler, H as HttpMethod } from '../common.type-BhGCNyEm.js';
 import { A as AzuraConfig } from '../config.type-s3ImgfM_.js';
 import { g as PluginHandler } from '../plugin.type-D4HHceYz.js';
-
-declare class Router {
-    private root;
-    private cache;
-    private staticRoutes;
-    constructor(cacheSize?: number);
-    add(method: HttpMethod, path: string, handler: RouteHandler, middlewares?: MiddlewareHandler[], meta?: Record<string, any>): void;
-    find(method: HttpMethod, path: string): RouteMatch | null;
-    private matchNode;
-    private normalizePath;
-    getAllRoutes(): Array<{
-        method: HttpMethod;
-        path: string;
-    }>;
-    private collectRoutes;
-}
+import { d as RouteMeta } from '../routes.type-DzHNkCag.js';
+import { B as BuildOpenApiOptions } from '../swagger.type-CfDbFCZC.js';
 
 declare class AzuraServer {
     private server;
@@ -33,14 +20,14 @@ declare class AzuraServer {
     use(handler: MiddlewareHandler | PluginHandler): this;
     plugin(handler: PluginHandler): this;
     onError(handler: ErrorHandler): this;
-    get(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    post(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    put(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    delete(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    patch(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    head(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    options(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
-    all(path: string, ...handlers: (MiddlewareHandler | Function)[]): this;
+    get(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    post(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    put(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    delete(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    patch(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    head(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    options(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
+    all(path: string, ...handlers: (MiddlewareHandler | Function | RouteMeta)[]): this;
     private route;
     register(...controllers: (new (...args: any[]) => any)[]): this;
     private registerController;
@@ -60,6 +47,10 @@ declare class AzuraServer {
         method: HttpMethod;
         path: string;
     }>;
+    /** Rotas com metadados OpenAPI (para Swagger ou export manual). */
+    getRouteDocuments(): RouteDocument[];
+    /** Gera documento OpenAPI 3.0 a partir das rotas registadas. */
+    getOpenApiDocument(options?: BuildOpenApiOptions): Record<string, unknown>;
 }
 
-export { AzuraServer, Router };
+export { AzuraServer, RouteDocument, Router };

package/dist/core/index.js

@@ -183,31 +183,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 });
       }
     }
   }
@@ -615,7 +621,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";
@@ -704,9 +877,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) {
@@ -719,6 +902,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"
@@ -734,6 +918,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);
@@ -745,7 +937,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) {
@@ -1099,6 +1291,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);
+  }
 };
 
 exports.AzuraServer = AzuraServer;