azurajs 3.0.2 → 3.0.4

package/src/swagger/openapi-builder.ts

@@ -0,0 +1,199 @@
+import type { HttpMethod } from "../types/common.type.js";
+import type { RouteDocument } from "../core/router.js";
+import type { RouteMeta } from "../types/routes.type.js";
+import type { BuildOpenApiOptions, OpenApiInfo } from "../types/swagger.type.js";
+
+function resolveInfo(options: BuildOpenApiOptions): OpenApiInfo {
+  return (
+    options.info ?? {
+      title: "AzuraJS API",
+      version: "1.0.0",
+      description: "Generated OpenAPI specification",
+    }
+  );
+}
+
+/** Converte path AzuraJS `/users/:id` → OpenAPI `/users/{id}` */
+export function toOpenApiPath(path: string): string {
+  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: string): Array<Record<string, unknown>> {
+  const re = /\{([^}]+)\}/g;
+  const out: Array<Record<string, unknown>> = [];
+  let m: RegExpExecArray | null;
+  const seen = new Set<string>();
+  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?: RouteMeta): Record<string, unknown> {
+  if (meta?.responses && Object.keys(meta.responses).length > 0) {
+    const out: Record<string, unknown> = {};
+    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: RouteMeta | undefined,
+  pathParams: Array<Record<string, unknown>>,
+): Array<Record<string, unknown>> {
+  const fromMeta = meta?.parameters ?? [];
+  const names = new Set(pathParams.map((p) => p.name as string));
+  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: import("../types/routes.type.js").ParameterMeta): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    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: HttpMethod, oPath: string): string {
+  const slug = oPath
+    .replace(/[/{}\-*]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "");
+  return `${method.toLowerCase()}_${slug || "root"}`;
+}
+
+function operationForMethod(
+  method: HttpMethod,
+  oPath: string,
+  meta: RouteMeta | undefined,
+): Record<string, unknown> {
+  const op: Record<string, unknown> = {
+    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;
+}
+
+/**
+ * Gera documento OpenAPI 3.0 a partir das rotas registadas.
+ */
+export function buildOpenApiDocument(
+  routes: RouteDocument[],
+  options: BuildOpenApiOptions,
+): Record<string, unknown> {
+  const info = resolveInfo(options);
+  const prefix = options.pathPrefix ?? "";
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  const seen = new Set<string>();
+  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,
+  };
+}

package/src/swagger/swagger-ui-html.ts

@@ -0,0 +1,24 @@
+/**
+ * HTML da UI de documentação OpenAPI (paridade visual com azurajs-legacy: sidebar, Inter/JetBrains Mono, tema zinc/indigo).
+ */
+import { SWAGGER_UI_MODERN_HTML } from "./swagger-ui-template.js";
+
+export function renderSwaggerUiPage(options: {
+  title: string;
+  specUrl: string;
+  deepLinking?: boolean;
+}): string {
+  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: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}