azurajs 3.0.2 → 3.0.4

package/dist/index.js

@@ -187,31 +187,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 });
       }
     }
   }
@@ -642,7 +648,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";
@@ -731,9 +904,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) {
@@ -746,6 +929,7 @@ var AzuraServer = class {
     const instance = new Controller2();
     const prefix = Reflect.getMetadata?.(CONTROLLER_META_KEY, Controller2) ?? "";
     const controllerMiddlewares = Reflect.getMetadata?.("azura:middlewares", Controller2) ?? [];
+    const controllerTags = Reflect.getMetadata?.(API_TAGS_KEY, Controller2) ?? [];
     const prototype = Controller2.prototype;
     const propertyNames = Object.getOwnPropertyNames(prototype).filter(
       (p) => p !== "constructor"
@@ -761,6 +945,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);
@@ -772,7 +964,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) {
@@ -1126,6 +1318,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);
+  }
 };
 
 // src/decorators/Route.ts
@@ -1225,6 +1425,24 @@ function Meta(key, value) {
   };
 }
 
+// src/swagger/decorators.ts
+function ApiTags(...tags) {
+  return function(target, propertyKey, _descriptor) {
+    if (propertyKey === void 0) {
+      Reflect.defineMetadata(API_TAGS_KEY, tags, target);
+    } else {
+      Reflect.defineMetadata(METHOD_TAGS_KEY, tags, target, String(propertyKey));
+    }
+  };
+}
+function ApiOperation(meta) {
+  return function(target, propertyKey, _descriptor) {
+    const key = String(propertyKey);
+    const cur = Reflect.getMetadata?.(API_OPERATION_KEY, target, key) ?? {};
+    Reflect.defineMetadata(API_OPERATION_KEY, { ...cur, ...meta }, target, key);
+  };
+}
+
 // src/plugins/CORSPlugin.ts
 var DEFAULT_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
 var DEFAULT_HEADERS = ["Content-Type", "Authorization", "Accept", "X-Requested-With"];
@@ -2258,6 +2476,949 @@ function bufferIndexOf(buf, search, offset) {
   return -1;
 }
 
+// src/swagger/swagger-ui-template.ts
+var SWAGGER_UI_MODERN_HTML = `<!DOCTYPE html>\r
+<html lang="en">\r
+\r
+<head>\r
+    <meta charset="UTF-8" />\r
+    <meta name="viewport" content="width=device-width,initial-scale=1.0" />\r
+    <title>__PAGE_TITLE__</title>\r
+    <link rel="preconnect" href="https://fonts.googleapis.com" />\r
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />\r
+    <link\r
+        href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"\r
+        rel="stylesheet" />\r
+    <style>\r
+        :root {\r
+            --bg-body: #09090b;\r
+            --bg-sidebar: #18181b;\r
+            --bg-card: #18181b;\r
+            --bg-card-hover: #27272a;\r
+            --bg-input: #09090b;\r
+            --border-color: #27272a;\r
+            --primary-color: #6366f1;\r
+            --primary-hover: #4f46e5;\r
+            --text-primary: #f4f4f5;\r
+            --text-secondary: #a1a1aa;\r
+            --text-muted: #52525b;\r
+            --success: #22c55e;\r
+            --warning: #eab308;\r
+            --danger: #ef4444;\r
+            --info: #3b82f6;\r
+            --font-sans: 'Inter', system-ui, -apple-system, sans-serif;\r
+            --font-mono: 'JetBrains Mono', monospace;\r
+        }\r
+\r
+        * {\r
+            margin: 0;\r
+            padding: 0;\r
+            box-sizing: border-box\r
+        }\r
+\r
+        body {\r
+            font-family: var(--font-sans);\r
+            background-color: var(--bg-body);\r
+            color: var(--text-primary);\r
+            line-height: 1.5;\r
+            height: 100vh;\r
+            overflow: hidden\r
+        }\r
+\r
+        ::-webkit-scrollbar {\r
+            width: 6px;\r
+            height: 6px\r
+        }\r
+\r
+        ::-webkit-scrollbar-track {\r
+            background: transparent\r
+        }\r
+\r
+        ::-webkit-scrollbar-thumb {\r
+            background: var(--border-color);\r
+            border-radius: 3px\r
+        }\r
+\r
+        ::-webkit-scrollbar-thumb:hover {\r
+            background: var(--text-muted)\r
+        }\r
+\r
+        .layout {\r
+            display: flex;\r
+            height: 100%\r
+        }\r
+\r
+        .sidebar {\r
+            width: 300px;\r
+            background: var(--bg-sidebar);\r
+            border-right: 1px solid var(--border-color);\r
+            display: flex;\r
+            flex-direction: column;\r
+            flex-shrink: 0\r
+        }\r
+\r
+        .sidebar-header {\r
+            padding: 20px;\r
+            border-bottom: 1px solid var(--border-color);\r
+            background: var(--bg-sidebar)\r
+        }\r
+\r
+        .api-title {\r
+            font-size: 1.25rem;\r
+            font-weight: 700;\r
+            color: var(--text-primary);\r
+            margin-bottom: 4px\r
+        }\r
+\r
+        .api-version {\r
+            font-size: 0.75rem;\r
+            color: var(--primary-color);\r
+            background: rgba(99, 102, 241, 0.1);\r
+            padding: 2px 8px;\r
+            border-radius: 12px;\r
+            font-family: var(--font-mono)\r
+        }\r
+\r
+        .search-box {\r
+            padding: 16px\r
+        }\r
+\r
+        .search-input {\r
+            width: 100%;\r
+            background: var(--bg-input);\r
+            border: 1px solid var(--border-color);\r
+            padding: 8px 12px;\r
+            border-radius: 6px;\r
+            color: var(--text-primary);\r
+            font-size: 0.875rem;\r
+            outline: none;\r
+            transition: border-color 0.2s\r
+        }\r
+\r
+        .search-input:focus {\r
+            border-color: var(--primary-color)\r
+        }\r
+\r
+        .nav-list {\r
+            flex: 1;\r
+            overflow-y: auto;\r
+            padding: 0 16px 20px\r
+        }\r
+\r
+        .nav-group-title {\r
+            font-size: 0.75rem;\r
+            text-transform: uppercase;\r
+            color: var(--text-muted);\r
+            font-weight: 600;\r
+            margin: 24px 0 8px;\r
+            letter-spacing: 0.05em\r
+        }\r
+\r
+        .nav-item {\r
+            display: flex;\r
+            align-items: center;\r
+            gap: 8px;\r
+            padding: 8px;\r
+            border-radius: 6px;\r
+            cursor: pointer;\r
+            transition: background 0.2s;\r
+            margin-bottom: 2px\r
+        }\r
+\r
+        .nav-item:hover {\r
+            background: var(--bg-card-hover)\r
+        }\r
+\r
+        .nav-item.active {\r
+            background: rgba(99, 102, 241, 0.1)\r
+        }\r
+\r
+        .method-tag {\r
+            font-family: var(--font-mono);\r
+            font-size: 0.65rem;\r
+            font-weight: 700;\r
+            padding: 2px 6px;\r
+            border-radius: 4px;\r
+            width: 45px;\r
+            text-align: center\r
+        }\r
+\r
+        .get {\r
+            color: var(--success);\r
+            background: rgba(34, 197, 94, 0.1)\r
+        }\r
+\r
+        .post {\r
+            color: var(--primary-color);\r
+            background: rgba(99, 102, 241, 0.1)\r
+        }\r
+\r
+        .put {\r
+            color: var(--warning);\r
+            background: rgba(234, 179, 8, 0.1)\r
+        }\r
+\r
+        .delete {\r
+            color: var(--danger);\r
+            background: rgba(239, 68, 68, 0.1)\r
+        }\r
+\r
+        .patch {\r
+            color: var(--info);\r
+            background: rgba(59, 130, 246, 0.1)\r
+        }\r
+\r
+        .nav-path {\r
+            font-size: 0.8rem;\r
+            color: var(--text-secondary);\r
+            white-space: nowrap;\r
+            overflow: hidden;\r
+            text-overflow: ellipsis;\r
+            font-family: var(--font-mono)\r
+        }\r
+\r
+        .main-content {\r
+            flex: 1;\r
+            overflow-y: auto;\r
+            padding: 40px;\r
+            scroll-behavior: smooth\r
+        }\r
+\r
+        .content-width {\r
+            max-width: 1000px;\r
+            margin: 0 auto\r
+        }\r
+\r
+        .info-section {\r
+            margin-bottom: 40px\r
+        }\r
+\r
+        .info-title {\r
+            font-size: 2.5rem;\r
+            font-weight: 800;\r
+            margin-bottom: 16px;\r
+            letter-spacing: -0.02em\r
+        }\r
+\r
+        .info-desc {\r
+            color: var(--text-secondary);\r
+            font-size: 1.1rem;\r
+            max-width: 700px\r
+        }\r
+\r
+        .server-section {\r
+            background: var(--bg-card);\r
+            border: 1px solid var(--border-color);\r
+            padding: 20px;\r
+            border-radius: 8px;\r
+            margin-bottom: 40px\r
+        }\r
+\r
+        .server-label {\r
+            display: block;\r
+            font-size: 0.875rem;\r
+            color: var(--text-muted);\r
+            margin-bottom: 8px\r
+        }\r
+\r
+        .server-select {\r
+            width: 100%;\r
+            background: var(--bg-input);\r
+            border: 1px solid var(--border-color);\r
+            color: var(--text-primary);\r
+            padding: 10px;\r
+            border-radius: 6px;\r
+            font-family: var(--font-mono);\r
+            font-size: 0.9rem\r
+        }\r
+\r
+        .endpoint-card {\r
+            background: var(--bg-card);\r
+            border: 1px solid var(--border-color);\r
+            border-radius: 8px;\r
+            margin-bottom: 24px;\r
+            overflow: hidden;\r
+            transition: border-color 0.2s\r
+        }\r
+\r
+        .endpoint-card:hover {\r
+            border-color: var(--text-muted)\r
+        }\r
+\r
+        .card-header {\r
+            padding: 16px 24px;\r
+            display: flex;\r
+            align-items: center;\r
+            gap: 16px;\r
+            cursor: pointer;\r
+            background: rgba(255, 255, 255, 0.02);\r
+            user-select: none\r
+        }\r
+\r
+        .card-summary {\r
+            flex: 1;\r
+            font-weight: 500;\r
+            font-size: 1rem\r
+        }\r
+\r
+        .card-path {\r
+            font-family: var(--font-mono);\r
+            font-size: 0.85rem;\r
+            color: var(--text-muted)\r
+        }\r
+\r
+        .chevron {\r
+            transition: transform 0.2s;\r
+            color: var(--text-muted)\r
+        }\r
+\r
+        .card-header[aria-expanded="true"] .chevron {\r
+            transform: rotate(180deg)\r
+        }\r
+\r
+        .card-body {\r
+            border-top: 1px solid var(--border-color);\r
+            padding: 24px;\r
+            display: none\r
+        }\r
+\r
+        .card-header[aria-expanded="true"]+.card-body {\r
+            display: block\r
+        }\r
+\r
+        .section-header {\r
+            font-size: 0.75rem;\r
+            text-transform: uppercase;\r
+            color: var(--text-muted);\r
+            font-weight: 700;\r
+            margin: 24px 0 12px;\r
+            letter-spacing: 0.05em\r
+        }\r
+\r
+        .section-header:first-child {\r
+            margin-top: 0\r
+        }\r
+\r
+        .params-table {\r
+            width: 100%;\r
+            border-collapse: collapse;\r
+            font-size: 0.9rem;\r
+            margin-bottom: 20px\r
+        }\r
+\r
+        .params-table th {\r
+            text-align: left;\r
+            color: var(--text-muted);\r
+            padding: 8px 12px;\r
+            font-weight: 500;\r
+            border-bottom: 1px solid var(--border-color);\r
+            font-size: 0.8rem\r
+        }\r
+\r
+        .params-table td {\r
+            padding: 12px;\r
+            border-bottom: 1px solid var(--border-color);\r
+            color: var(--text-secondary);\r
+            vertical-align: top\r
+        }\r
+\r
+        .params-table tr:last-child td {\r
+            border-bottom: none\r
+        }\r
+\r
+        .param-name {\r
+            font-family: var(--font-mono);\r
+            color: var(--text-primary);\r
+            font-weight: 600\r
+        }\r
+\r
+        .param-req {\r
+            color: var(--danger);\r
+            font-size: 0.7rem;\r
+            margin-left: 4px\r
+        }\r
+\r
+        .param-meta {\r
+            font-size: 0.8rem;\r
+            color: var(--text-muted);\r
+            margin-top: 4px;\r
+            font-family: var(--font-mono)\r
+        }\r
+\r
+        .code-block {\r
+            background: #000;\r
+            border: 1px solid var(--border-color);\r
+            border-radius: 6px;\r
+            padding: 16px;\r
+            font-family: var(--font-mono);\r
+            font-size: 0.85rem;\r
+            overflow-x: auto;\r
+            color: #d4d4d8\r
+        }\r
+\r
+        .try-it-box {\r
+            background: rgba(99, 102, 241, 0.05);\r
+            border: 1px solid rgba(99, 102, 241, 0.2);\r
+            border-radius: 8px;\r
+            padding: 20px;\r
+            margin-top: 32px\r
+        }\r
+\r
+        .form-grid {\r
+            display: grid;\r
+            grid-template-columns: 1fr;\r
+            gap: 16px;\r
+            margin-bottom: 20px\r
+        }\r
+\r
+        .form-group label {\r
+            display: block;\r
+            font-size: 0.8rem;\r
+            font-weight: 600;\r
+            margin-bottom: 6px;\r
+            color: var(--text-secondary)\r
+        }\r
+\r
+        .form-group input {\r
+            width: 100%;\r
+            background: var(--bg-body);\r
+            border: 1px solid var(--border-color);\r
+            padding: 8px 12px;\r
+            border-radius: 4px;\r
+            color: var(--text-primary);\r
+            font-family: var(--font-mono);\r
+            font-size: 0.85rem\r
+        }\r
+\r
+        .form-group input:focus {\r
+            border-color: var(--primary-color);\r
+            outline: none\r
+        }\r
+\r
+        .body-editor {\r
+            width: 100%;\r
+            height: 200px;\r
+            background: var(--bg-body);\r
+            border: 1px solid var(--border-color);\r
+            border-radius: 6px;\r
+            padding: 12px;\r
+            color: var(--text-primary);\r
+            font-family: var(--font-mono);\r
+            font-size: 0.85rem;\r
+            resize: vertical;\r
+            margin-bottom: 16px\r
+        }\r
+\r
+        .action-btn {\r
+            background: var(--primary-color);\r
+            color: white;\r
+            border: none;\r
+            padding: 10px 20px;\r
+            border-radius: 6px;\r
+            font-weight: 600;\r
+            cursor: pointer;\r
+            font-size: 0.9rem;\r
+            transition: background 0.2s;\r
+            display: inline-flex;\r
+            align-items: center;\r
+            gap: 8px\r
+        }\r
+\r
+        .action-btn:hover {\r
+            background: var(--primary-hover)\r
+        }\r
+\r
+        .action-btn:disabled {\r
+            opacity: 0.6;\r
+            cursor: not-allowed\r
+        }\r
+\r
+        .response-area {\r
+            margin-top: 20px;\r
+            border-top: 1px solid var(--border-color);\r
+            padding-top: 20px\r
+        }\r
+\r
+        .status-badge {\r
+            display: inline-block;\r
+            padding: 4px 8px;\r
+            border-radius: 4px;\r
+            font-size: 0.8rem;\r
+            font-weight: 700;\r
+            margin-bottom: 10px;\r
+            font-family: var(--font-mono)\r
+        }\r
+\r
+        .status-2xx {\r
+            background: rgba(34, 197, 94, 0.2);\r
+            color: var(--success)\r
+        }\r
+\r
+        .status-4xx,\r
+        .status-5xx {\r
+            background: rgba(239, 68, 68, 0.2);\r
+            color: var(--danger)\r
+        }\r
+\r
+        .loader {\r
+            width: 16px;\r
+            height: 16px;\r
+            border: 2px solid #ffffff;\r
+            border-bottom-color: transparent;\r
+            border-radius: 50%;\r
+            display: inline-block;\r
+            animation: rotation 1s linear infinite\r
+        }\r
+\r
+        @keyframes rotation {\r
+            0% {\r
+                transform: rotate(0deg)\r
+            }\r
+\r
+            100% {\r
+                transform: rotate(360deg)\r
+            }\r
+        }\r
+\r
+        @media (max-width:768px) {\r
+            .layout {\r
+                flex-direction: column;\r
+                overflow: auto\r
+            }\r
+\r
+            .sidebar {\r
+                width: 100%;\r
+                height: auto;\r
+                border-right: none;\r
+                border-bottom: 1px solid var(--border-color)\r
+            }\r
+\r
+            .main-content {\r
+                padding: 20px;\r
+                overflow: visible\r
+            }\r
+\r
+            .nav-list {\r
+                max-height: 300px\r
+            }\r
+        }\r
+    </style>\r
+</head>\r
+\r
+<body>\r
+    <div class="layout">\r
+        <aside class="sidebar">\r
+            <div class="sidebar-header">\r
+                <div class="api-title" id="apiTitle">API Docs</div>\r
+                <span class="api-version" id="apiVersion">v1.0.0</span>\r
+            </div>\r
+            <div class="search-box">\r
+                <input type="text" class="search-input" id="searchNav" placeholder="Filter endpoints...">\r
+            </div>\r
+            <div class="nav-list" id="navList"></div>\r
+        </aside>\r
+        <main class="main-content">\r
+            <div class="content-width">\r
+                <div class="info-section">\r
+                    <h1 class="info-title" id="docTitle">API Reference</h1>\r
+                    <p class="info-desc" id="docDesc">Loading documentation...</p>\r
+                </div>\r
+                <div class="server-section">\r
+                    <label class="server-label">Base URL</label>\r
+                    <select class="server-select" id="serverUrl"></select>\r
+                </div>\r
+                <div id="endpointsContainer"></div>\r
+            </div>\r
+        </main>\r
+    </div>\r
+\r
+    <script>\r
+        const state = { spec: null, server: '' };\r
+        function sanitizeId(str) { return String(str).replace(/[^a-zA-Z0-9_-]/g, '_'); }\r
+        async function init() {\r
+            try {\r
+                const res = await fetch("___AZURA_SPEC_URL_PLACEHOLDER___");\r
+                if (!res.ok) throw new Error('Spec not found');\r
+                state.spec = await res.json();\r
+                renderHeader();\r
+                renderServers();\r
+                renderNavigation();\r
+                renderEndpoints();\r
+                setupSearch();\r
+                attachGlobalListeners();\r
+            } catch (err) {\r
+                const descEl = document.getElementById('docDesc');\r
+                descEl.textContent = 'Failed to load API definition. Check that the OpenAPI JSON endpoint is configured and reachable.';\r
+                descEl.style.color = 'var(--danger)';\r
+            }\r
+        }\r
+\r
+        function renderHeader() {\r
+            const info = state.spec.info || {};\r
+            document.title = \`\${info.title || 'API'} - Docs\`;\r
+            document.getElementById('apiTitle').textContent = info.title || 'API';\r
+            document.getElementById('apiVersion').textContent = info.version ? \`v\${info.version}\` : '';\r
+            document.getElementById('docTitle').textContent = info.title || 'API Reference';\r
+            document.getElementById('docDesc').textContent = info.description || 'No description provided.';\r
+        }\r
+\r
+        function renderServers() {\r
+            const select = document.getElementById('serverUrl');\r
+            const servers = state.spec.servers && state.spec.servers.length ? state.spec.servers : [{ url: window.location.origin, description: 'Current Origin' }];\r
+            select.innerHTML = servers.map(s => \`<option value="\${s.url}">\${s.url}\${s.description ? \` (\${s.description})\` : ''}</option>\`).join('');\r
+            state.server = servers[0].url;\r
+            select.addEventListener('change', (e) => state.server = e.target.value);\r
+        }\r
+\r
+        function renderNavigation() {\r
+            const nav = document.getElementById('navList');\r
+            const tags = {};\r
+            Object.entries(state.spec.paths || {}).forEach(([path, methods]) => {\r
+                Object.entries(methods).forEach(([method, op]) => {\r
+                    const tag = (op.tags && op.tags[0]) ? op.tags[0] : 'General';\r
+                    if (!tags[tag]) tags[tag] = [];\r
+                    tags[tag].push({ path, method, op });\r
+                });\r
+            });\r
+\r
+            let html = '';\r
+            Object.entries(tags).forEach(([tag, items]) => {\r
+                html += \`<div class="nav-group-title">\${tag}</div>\`;\r
+                items.forEach(item => {\r
+                    const label = item.op.summary || item.path;\r
+                    const filter = \`\${item.method} \${item.path} \${label}\`.toLowerCase();\r
+                    const targetId = sanitizeId(\`\${item.method}-\${item.path}\`);\r
+                    html += \`<div class="nav-item" data-filter="\${escapeHtmlAttr(filter)}" data-target-id="\${escapeHtmlAttr(targetId)}">\r
+                                <span class="method-tag \${item.method.toLowerCase()}">\${item.method.toUpperCase()}</span>\r
+                                <span class="nav-path">\${escapeHtmlAttr(label)}</span>\r
+                             </div>\`;\r
+                });\r
+            });\r
+\r
+            nav.innerHTML = html;\r
+            nav.querySelectorAll('.nav-item').forEach(el => {\r
+                el.addEventListener('click', () => {\r
+                    const tid = el.dataset.targetId;\r
+                    scrollEndpoint(tid);\r
+                    document.querySelectorAll('.nav-item').forEach(i => i.classList.toggle('active', i === el));\r
+                });\r
+            });\r
+        }\r
+\r
+        function renderEndpoints() {\r
+            const container = document.getElementById('endpointsContainer');\r
+            container.innerHTML = '';\r
+            Object.entries(state.spec.paths || {}).forEach(([path, methods]) => {\r
+                Object.entries(methods).forEach(([method, op]) => {\r
+                    container.appendChild(createEndpointCard(path, method, op));\r
+                });\r
+            });\r
+        }\r
+\r
+        function createEndpointCard(path, method, op) {\r
+            const rawId = \`\${method}-\${path}\`;\r
+            const id = sanitizeId(rawId);\r
+            const card = document.createElement('div');\r
+            card.className = 'endpoint-card';\r
+            card.id = id;\r
+\r
+            const descriptionHtml = op.description ? \`<p style="margin-bottom:20px;color:var(--text-secondary)">\${escapeHtml(op.description)}</p>\` : '';\r
+            const paramsHtml = renderParameters(op.parameters);\r
+            const requestBodyHtml = renderRequestBody(op.requestBody);\r
+            const responsesHtml = renderResponses(op.responses);\r
+\r
+            const inputsId = \`inputs_\${id}\`;\r
+            const bodyId = \`body_\${id}\`;\r
+            const tryButtonId = \`btn_\${id}\`;\r
+            const inputsHtmlForTry = (op.parameters || []).map(p => {\r
+                const placeholder = p.schema?.type || '';\r
+                const required = p.required ? ' <span style="color:var(--danger)">*</span>' : '';\r
+                return \`<div class="form-group">\r
+                            <label>\${escapeHtml(p.name)} <span style="font-weight:400;color:var(--text-muted)">(\${escapeHtml(p.in)})</span>\${required}</label>\r
+                            <input type="text" data-name="\${escapeHtmlAttr(p.name)}" data-in="\${escapeHtmlAttr(p.in)}" placeholder="\${escapeHtmlAttr(placeholder)}">\r
+                        </div>\`;\r
+            }).join('');\r
+\r
+            const bodyEditorHtml = op.requestBody ? \`<div class="form-group">\r
+                    <label>Request Body (JSON)</label>\r
+                    <textarea class="body-editor" id="\${bodyId}">\${getExampleBody(op.requestBody)}</textarea>\r
+                </div>\` : '';\r
+\r
+            card.innerHTML = \`\r
+                <div class="card-header" aria-expanded="false">\r
+                    <span class="method-tag \${method.toLowerCase()}">\${method.toUpperCase()}</span>\r
+                    <span class="card-summary">\${escapeHtml(op.summary || path)}</span>\r
+                    <span class="card-path">\${escapeHtml(path)}</span>\r
+                    <svg class="chevron" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg>\r
+                </div>\r
+                <div class="card-body">\r
+                    \${descriptionHtml}\r
+                    \${paramsHtml}\r
+                    \${requestBodyHtml}\r
+                    <div class="try-it-box">\r
+                        <div class="section-header">Try It Out</div>\r
+                        <div class="form-grid" id="\${inputsId}">\r
+                            \${inputsHtmlForTry}\r
+                        </div>\r
+                        \${bodyEditorHtml}\r
+                        <button class="action-btn" id="\${tryButtonId}" data-method="\${escapeHtmlAttr(method)}" data-path="\${escapeHtmlAttr(path)}" data-card-id="\${escapeHtmlAttr(id)}">\r
+                            <span>Execute Request</span>\r
+                        </button>\r
+                        <div class="response-area" style="display:none"></div>\r
+                    </div>\r
+                    \${responsesHtml}\r
+                </div>\r
+            \`;\r
+\r
+            return card;\r
+        }\r
+\r
+        function renderParameters(params) {\r
+            if (!params || params.length === 0) return '';\r
+            return \`\r
+                <div class="section-header">Parameters</div>\r
+                <table class="params-table">\r
+                    <thead><tr><th>Name</th><th>Description</th></tr></thead>\r
+                    <tbody>\r
+                        \${params.map(p => \`\r
+                            <tr>\r
+                                <td>\r
+                                    <div class="param-name">\${escapeHtml(p.name)}\${p.required ? '<span class="param-req">*</span>' : ''}</div>\r
+                                    <div class="param-meta">\${escapeHtml(p.in)} &bull; \${escapeHtml(p.schema?.type || 'string')}</div>\r
+                                </td>\r
+                                <td>\${escapeHtml(p.description || '-')}</td>\r
+                            </tr>\r
+                        \`).join('')}\r
+                    </tbody>\r
+                </table>\r
+            \`;\r
+        }\r
+\r
+        function renderRequestBody(body) {\r
+            if (!body) return '';\r
+            const contentType = Object.keys(body.content || {})[0] || 'application/json';\r
+            const schema = body.content && body.content[contentType] ? body.content[contentType].schema : null;\r
+            return \`\r
+                <div class="section-header">Request Body <span style="font-weight:400;text-transform:none;color:var(--text-secondary)">(\${escapeHtml(contentType)})</span></div>\r
+                <div class="code-block">\${escapeHtml(JSON.stringify(generateExample(schema), null, 2))}</div>\r
+            \`;\r
+        }\r
+\r
+        function renderResponses(responses) {\r
+            if (!responses) return '';\r
+            return \`\r
+                <div class="section-header">Responses</div>\r
+                \${Object.entries(responses).map(([status, res]) => \`\r
+                    <div style="margin-bottom:16px">\r
+                        <div style="font-weight:600;font-family:var(--font-mono);margin-bottom:4px">\r
+                            <span style="color:\${String(status).startsWith('2') ? 'var(--success)' : 'var(--danger)'}">\${escapeHtml(status)}</span>\r
+                            <span style="color:var(--text-secondary)">\${escapeHtml(res.description || '')}</span>\r
+                        </div>\r
+                    </div>\r
+                \`).join('')}\r
+            \`;\r
+        }\r
+\r
+        function getExampleBody(body) {\r
+            if (!body || !body.content) return '{}';\r
+            const contentType = Object.keys(body.content)[0];\r
+            const schema = body.content[contentType].schema;\r
+            try { return JSON.stringify(generateExample(schema), null, 2); } catch { return '{}'; }\r
+        }\r
+\r
+        function generateExample(schema) {\r
+            if (!schema) return {};\r
+            if (schema.example !== undefined) return schema.example;\r
+            if (schema.$ref) {\r
+                const ref = String(schema.$ref).replace(/^#\\/components\\/schemas\\//, '');\r
+                const comp = state.spec.components && state.spec.components.schemas && state.spec.components.schemas[ref];\r
+                if (comp) return generateExample(comp);\r
+                return {};\r
+            }\r
+            if (schema.type === 'object' && schema.properties) {\r
+                const obj = {};\r
+                for (const [k, prop] of Object.entries(schema.properties)) {\r
+                    obj[k] = generateExample(prop);\r
+                }\r
+                return obj;\r
+            }\r
+            if (schema.type === 'array') return [generateExample(schema.items)];\r
+            if (schema.type === 'string') return 'string';\r
+            if (schema.type === 'integer' || schema.type === 'number') return 0;\r
+            if (schema.type === 'boolean') return true;\r
+            return null;\r
+        }\r
+\r
+        async function executeRequest(method, path, btn) {\r
+            const cardId = btn.dataset.cardId;\r
+            const card = document.getElementById(cardId);\r
+            const inputs = card.querySelectorAll('input[data-name]');\r
+            const bodyEditor = card.querySelector('.body-editor');\r
+            const responseArea = card.querySelector('.response-area');\r
+            const originalHtml = btn.innerHTML;\r
+            btn.disabled = true;\r
+            btn.innerHTML = '<span class="loader"></span> Executing...';\r
+            responseArea.style.display = 'none';\r
+            try {\r
+                let url = (state.server || '') + path;\r
+                const headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' };\r
+                const queryParams = new URLSearchParams();\r
+                inputs.forEach(input => {\r
+                    const value = input.value.trim();\r
+                    if (!value) return;\r
+                    const type = input.dataset.in;\r
+                    const name = input.dataset.name;\r
+                    if (type === 'path') {\r
+                        url = url.replace(\`{\${name}}\`, encodeURIComponent(value));\r
+                    } else if (type === 'query') {\r
+                        queryParams.append(name, value);\r
+                    } else if (type === 'header') {\r
+                        headers[name] = value;\r
+                    } else if (type === 'cookie') {\r
+                        // cookies handled as header for demo purposes\r
+                        headers['Cookie'] = (headers['Cookie'] ? headers['Cookie'] + '; ' : '') + \`\${name}=\${value}\`;\r
+                    }\r
+                });\r
+                const qs = queryParams.toString();\r
+                if (qs) url += \`?\${qs}\`;\r
+                const options = { method: method.toUpperCase(), headers };\r
+                if (bodyEditor && ['POST', 'PUT', 'PATCH'].includes(method.toUpperCase())) {\r
+                    try {\r
+                        const parsed = JSON.parse(bodyEditor.value);\r
+                        options.body = JSON.stringify(parsed);\r
+                    } catch (e) {\r
+                        alert('Invalid JSON in Request Body');\r
+                        throw new Error('Invalid JSON');\r
+                    }\r
+                }\r
+                const start = performance.now();\r
+                const res = await fetch(url, options);\r
+                const duration = Math.round(performance.now() - start);\r
+                let data;\r
+                const ct = res.headers.get('content-type') || '';\r
+                if (ct.includes('application/json')) data = await res.json(); else data = await res.text();\r
+                const statusClass = res.ok ? 'status-2xx' : (String(res.status).startsWith('5') ? 'status-5xx' : 'status-4xx');\r
+                responseArea.style.display = 'block';\r
+                responseArea.innerHTML = \`\r
+                    <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:12px;">\r
+                        <span class="status-badge \${statusClass}">\${res.status} \${escapeHtml(res.statusText)}</span>\r
+                        <span style="font-family:var(--font-mono);font-size:0.8rem;color:var(--text-muted)">\${duration}ms</span>\r
+                    </div>\r
+                    <div class="section-header">Response Body</div>\r
+                    <div class="code-block">\${escapeHtml(typeof data === 'object' ? JSON.stringify(data, null, 2) : String(data))}</div>\r
+                    <div class="section-header">Response Headers</div>\r
+                    <div class="code-block">\${escapeHtml(Array.from(res.headers.entries()).map(([k, v]) => \`\${k}: \${v}\`).join('\\\\n'))}</div>\r
+                \`;\r
+            } catch (err) {\r
+                responseArea.style.display = 'block';\r
+                responseArea.innerHTML = \`<div style="color:var(--danger);font-weight:600">Error: \${escapeHtml(err.message || String(err))}</div>\`;\r
+            } finally {\r
+                btn.disabled = false;\r
+                btn.innerHTML = originalHtml;\r
+            }\r
+        }\r
+\r
+        function toggleCard(header) {\r
+            const isExpanded = header.getAttribute('aria-expanded') === 'true';\r
+            header.setAttribute('aria-expanded', String(!isExpanded));\r
+        }\r
+\r
+        function scrollEndpoint(sanitizedId) {\r
+            const el = document.getElementById(sanitizedId);\r
+            if (!el) return;\r
+            el.scrollIntoView({ behavior: 'smooth', block: 'start' });\r
+            const header = el.querySelector('.card-header');\r
+            if (header && header.getAttribute('aria-expanded') !== 'true') {\r
+                header.setAttribute('aria-expanded', 'true');\r
+            }\r
+        }\r
+\r
+        function setupSearch() {\r
+            const input = document.getElementById('searchNav');\r
+            input.addEventListener('input', (e) => {\r
+                const val = e.target.value.toLowerCase();\r
+                document.querySelectorAll('.nav-item').forEach(el => {\r
+                    const filter = el.dataset.filter || '';\r
+                    el.style.display = filter.includes(val) ? 'flex' : 'none';\r
+                });\r
+            });\r
+        }\r
+\r
+        function attachGlobalListeners() {\r
+            document.querySelectorAll('.endpoint-card .card-header').forEach(header => {\r
+                header.addEventListener('click', () => toggleCard(header));\r
+            });\r
+            document.querySelectorAll('.action-btn').forEach(btn => {\r
+                btn.addEventListener('click', () => executeRequest(btn.dataset.method, btn.dataset.path, btn));\r
+            });\r
+        }\r
+\r
+        function escapeHtml(str) {\r
+            if (str === undefined || str === null) return '';\r
+            return String(str)\r
+                .replace(/&/g, '&amp;')\r
+                .replace(/</g, '&lt;')\r
+                .replace(/>/g, '&gt;')\r
+                .replace(/"/g, '&quot;')\r
+                .replace(/'/g, '&#39;');\r
+        }\r
+        function escapeHtmlAttr(str) {\r
+            return escapeHtml(str).replace(/"/g, '&quot;').replace(/'/g, '&#39;');\r
+        }\r
+\r
+        init();\r
+    </script>\r
+</body>\r
+\r
+</html>`;
+
+// src/swagger/swagger-ui-html.ts
+function renderSwaggerUiPage(options) {
+  const { title, specUrl } = options;
+  return SWAGGER_UI_MODERN_HTML.replaceAll("__PAGE_TITLE__", escapeHtml(title)).replaceAll(
+    '"___AZURA_SPEC_URL_PLACEHOLDER___"',
+    JSON.stringify(specUrl)
+  );
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+// src/plugins/SwaggerPlugin.ts
+function SwaggerPlugin(options) {
+  const {
+    getDocuments,
+    specPath = "/openapi.json",
+    docsPath = "/docs",
+    deepLinking = true,
+    servers,
+    pathPrefix,
+    info
+  } = options;
+  const title = info?.title ?? "API";
+  return async (ctx, next) => {
+    const { req, res } = ctx;
+    const path = req.pathname ?? "";
+    if (path === specPath || path === `${specPath}/`) {
+      const doc = buildOpenApiDocument(getDocuments(), {
+        info: info ?? { title, version: "1.0.0" },
+        servers,
+        pathPrefix
+      });
+      res.json(doc);
+      return;
+    }
+    if (path === docsPath || path === `${docsPath}/`) {
+      const html = renderSwaggerUiPage({
+        title,
+        specUrl: specPath});
+      res.html(html);
+      return;
+    }
+    next();
+  };
+}
+
 // src/utils/validators/DTOValidator.ts
 var DTOValidator = class {
   static validate(data, schema) {
@@ -2536,6 +3697,8 @@ function LoggingMiddleware() {
   };
 }
 
+exports.ApiOperation = ApiOperation;
+exports.ApiTags = ApiTags;
 exports.AzuraServer = AzuraServer;
 exports.Body = Body;
 exports.CORSPlugin = CORSPlugin;
@@ -2580,6 +3743,7 @@ exports.SchemaValidator = SchemaValidator;
 exports.Session = Session;
 exports.SessionPlugin = SessionPlugin;
 exports.StaticPlugin = StaticPlugin;
+exports.SwaggerPlugin = SwaggerPlugin;
 exports.TimeoutPlugin = TimeoutPlugin;
 exports.UseMiddleware = UseMiddleware;
 exports.applyDecorators = applyDecorators;