@forinda/kickjs-swagger 2.0.1 → 2.1.0

package/dist/index.d.mts

@@ -0,0 +1,179 @@
+
+import { AdapterContext, AppAdapter } from "@forinda/kickjs";
+
+//#region src/schema-parser.d.ts
+/**
+ * Interface for converting validation library schemas to JSON Schema.
+ *
+ * KickJS ships with a Zod parser by default. To use a different validation
+ * library (Yup, Joi, Valibot, ArkType, etc.), implement this interface and
+ * pass it to the SwaggerAdapter.
+ *
+ * @example
+ * ```ts
+ * import Joi from 'joi'
+ * import joiToJson from 'joi-to-json'
+ *
+ * const joiParser: SchemaParser = {
+ *   name: 'joi',
+ *   supports: (schema) => Joi.isSchema(schema),
+ *   toJsonSchema: (schema) => joiToJson(schema),
+ * }
+ *
+ * new SwaggerAdapter({ schemaParser: joiParser })
+ * ```
+ */
+interface SchemaParser {
+  /** Human-readable name for logging/debugging */
+  readonly name: string;
+  /**
+   * Return true if this parser can handle the given schema object.
+   * Called before `toJsonSchema` to allow graceful fallback.
+   */
+  supports(schema: unknown): boolean;
+  /**
+   * Convert a validation schema to a JSON Schema object.
+   * Should return a plain object conforming to JSON Schema draft-07 or later.
+   * Must not include the top-level `$schema` key — the builder adds it.
+   */
+  toJsonSchema(schema: unknown): Record<string, unknown>;
+}
+/**
+ * Default schema parser for Zod v4+.
+ * Uses Zod's built-in `.toJSONSchema()` instance method.
+ */
+declare const zodSchemaParser: SchemaParser;
+//#endregion
+//#region src/decorators.d.ts
+interface ApiOperationOptions {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  deprecated?: boolean;
+}
+interface ApiResponseOptions {
+  status: number;
+  description?: string;
+  schema?: any;
+  /** Schema name in components/schemas (e.g., 'UserResponse', 'ErrorBody'). Auto-generated from handler name if omitted. */
+  name?: string;
+}
+/** Attach operation metadata to a route handler */
+declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
+/** Document a response status. Can be stacked multiple times. */
+declare function ApiResponse(options: ApiResponseOptions): MethodDecorator;
+/** Apply OpenAPI tags at class or method level */
+declare function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator;
+/** Mark endpoint as requiring Bearer token auth */
+declare function ApiBearerAuth(name?: string): ClassDecorator & MethodDecorator;
+/** Exclude a controller or method from the OpenAPI spec */
+declare function ApiExclude(): ClassDecorator & MethodDecorator;
+//#endregion
+//#region src/openapi-builder.d.ts
+interface OpenAPIInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+interface SwaggerOptions {
+  info?: Partial<OpenAPIInfo>;
+  servers?: {
+    url: string;
+    description?: string;
+  }[];
+  bearerAuth?: boolean;
+  /**
+   * Pluggable schema parser for converting validation schemas to JSON Schema.
+   * Defaults to `zodSchemaParser` which handles Zod v4+ schemas.
+   *
+   * Override this to use Yup, Joi, Valibot, ArkType, or any other library.
+   *
+   * @example
+   * ```ts
+   * new SwaggerAdapter({
+   *   schemaParser: myYupParser,
+   * })
+   * ```
+   */
+  schemaParser?: SchemaParser;
+}
+/** Register a controller for OpenAPI introspection (called by Application during route mounting) */
+declare function registerControllerForDocs(controllerClass: any, mountPath: string): void;
+/** Clear all registered routes (for HMR) */
+declare function clearRegisteredRoutes(): void;
+/** Build a full OpenAPI 3.0.3 spec from registered controllers and their decorators */
+declare function buildOpenAPISpec(options?: SwaggerOptions): any;
+//#endregion
+//#region src/swagger.adapter.d.ts
+interface SwaggerAdapterOptions extends SwaggerOptions {
+  /** Path to serve Swagger UI (default: '/docs') */
+  docsPath?: string;
+  /** Path to serve ReDoc (default: '/redoc') */
+  redocPath?: string;
+  /** Path to serve the raw JSON spec (default: '/openapi.json') */
+  specPath?: string;
+  /** Other adapters to discover (e.g., WsAdapter for WebSocket server URLs) */
+  adapters?: any[];
+}
+/**
+ * Swagger adapter — auto-generates OpenAPI spec from decorators and serves docs.
+ *
+ * Assets are served locally from `swagger-ui-dist` (npm dependency) —
+ * no CDN required, works fully offline.
+ *
+ * @example
+ * ```ts
+ * bootstrap({
+ *   modules,
+ *   adapters: [
+ *     new SwaggerAdapter({
+ *       info: { title: 'My API', version: '1.0.0' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * Endpoints:
+ *   GET /docs         — Swagger UI (local assets, no CDN)
+ *   GET /redoc        — ReDoc (CDN — no local package available)
+ *   GET /openapi.json — Raw OpenAPI 3.0.3 spec
+ */
+declare class SwaggerAdapter implements AppAdapter {
+  private options;
+  name: string;
+  constructor(options?: SwaggerAdapterOptions);
+  /** Auto-detect server URLs from the running HTTP server and peer adapters */
+  afterStart({
+    server
+  }: AdapterContext): void;
+  /** Collect controller metadata as routes are mounted */
+  onRouteMount(controllerClass: any, mountPath: string): void;
+  beforeMount({
+    app
+  }: AdapterContext): void;
+}
+//#endregion
+//#region src/ui.d.ts
+/**
+ * Generate Swagger UI HTML using local assets from swagger-ui-dist.
+ *
+ * Assets are served from `/_swagger-assets/` by the adapter's Express
+ * static middleware. Falls back to CDN if the local path is not provided.
+ * This ensures Swagger UI works fully offline in development.
+ *
+ * @param specUrl - Path to the OpenAPI JSON spec (e.g., '/openapi.json')
+ * @param title - Page title
+ * @param assetsPath - Base path for local swagger-ui-dist assets (e.g., '/_swagger-assets')
+ */
+declare function swaggerUIHtml(specUrl: string, title?: string, assetsPath?: string): string;
+/**
+ * Generate ReDoc HTML.
+ *
+ * ReDoc doesn't publish a standalone npm package suitable for local serving,
+ * so it still loads from CDN. If offline support for ReDoc is needed,
+ * vendor the standalone bundle into the package's public/ directory.
+ */
+declare function redocHtml(specUrl: string, title?: string): string;
+//#endregion
+export { ApiBearerAuth, ApiExclude, ApiOperation, type ApiOperationOptions, ApiResponse, type ApiResponseOptions, ApiTags, type OpenAPIInfo, type SchemaParser, SwaggerAdapter, type SwaggerAdapterOptions, type SwaggerOptions, buildOpenAPISpec, clearRegisteredRoutes, redocHtml, registerControllerForDocs, swaggerUIHtml, zodSchemaParser };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/schema-parser.ts","../src/decorators.ts","../src/openapi-builder.ts","../src/swagger.adapter.ts","../src/ui.ts"],"mappings":";;;;;;;AAqBA;;;;;;;;;;;;AAsBA;;;;;;UAtBiB,YAAA;;WAEN,IAAA;ECXyB;;;;EDiBlC,QAAA,CAAS,MAAA;ECdT;;;;AAIF;EDiBE,YAAA,CAAa,MAAA,YAAkB,MAAA;AAAA;;;;;cAOpB,eAAA,EAAiB,YAAA;;;UC/Bb,mBAAA;EACf,OAAA;EACA,WAAA;EACA,WAAA;EACA,UAAA;AAAA;AAAA,UAGe,kBAAA;EACf,MAAA;EACA,WAAA;EACA,MAAA;EDqB4B;ECnB5B,IAAA;AAAA;;iBAIc,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,eAAA;AAhB5D;AAAA,iBAuBgB,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,eAAA;;iBAY1C,OAAA,CAAA,GAAW,IAAA,aAAiB,cAAA,GAAiB,eAAA;;iBAW7C,aAAA,CAAc,IAAA,YAAsB,cAAA,GAAiB,eAAA;;iBAWrD,UAAA,CAAA,GAAc,cAAA,GAAiB,eAAA;;;UCxD9B,WAAA;EACf,KAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,cAAA;EACf,IAAA,GAAO,OAAA,CAAQ,WAAA;EACf,OAAA;IAAY,GAAA;IAAa,WAAA;EAAA;EACzB,UAAA;EFcqC;;AAOvC;;;;;;;;AC/BA;;;ECwBE,YAAA,GAAe,YAAA;AAAA;;iBAWD,yBAAA,CAA0B,eAAA,OAAsB,SAAA;;iBAKhD,qBAAA,CAAA;;iBAKA,gBAAA,CAAiB,OAAA,GAAS,cAAA;;;UCjCzB,qBAAA,SAA8B,cAAA;EHH9B;EGKf,QAAA;;EAEA,SAAA;EHLS;EGOT,QAAA;EHDS;EGGT,QAAA;AAAA;;;;AHWF;;;;;;;;AC/BA;;;;;;;;;;AAOA;;cEuCa,cAAA,YAA0B,UAAA;EAAA,QAGjB,OAAA;EAFpB,IAAA;cAEoB,OAAA,GAAS,qBAAA;EFvC7B;EE0CA,UAAA,CAAA;IAAa;EAAA,GAAU,cAAA;EFxCnB;EEmEJ,YAAA,CAAa,eAAA,OAAsB,SAAA;EAInC,WAAA,CAAA;IAAc;EAAA,GAAO,cAAA;AAAA;;;;;;AH1EvB;;;;;;;;iBIAgB,aAAA,CAAc,OAAA,UAAiB,KAAA,WAAoB,UAAA;;;;AJsBnE;;;;iBI0BgB,SAAA,CAAU,OAAA,UAAiB,KAAA"}

package/dist/index.mjs

@@ -0,0 +1,497 @@
+/**
+ * @forinda/kickjs-swagger v2.1.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { createRequire } from "node:module";
+import { Logger, METADATA, getClassMeta, getClassMetaOrUndefined, getMethodMeta, getMethodMetaOrUndefined, hasClassMeta, joinPaths, pushMethodMeta, setClassMeta, setMethodMeta } from "@forinda/kickjs";
+import { dirname } from "node:path";
+import express, { Router } from "express";
+//#region src/schema-parser.ts
+/**
+* Default schema parser for Zod v4+.
+* Uses Zod's built-in `.toJSONSchema()` instance method.
+*/
+const zodSchemaParser = {
+	name: "zod",
+	supports(schema) {
+		return schema != null && typeof schema === "object" && typeof schema.safeParse === "function" && typeof schema.toJSONSchema === "function";
+	},
+	toJsonSchema(schema) {
+		const { $schema: _, ...rest } = schema.toJSONSchema();
+		return rest;
+	}
+};
+//#endregion
+//#region src/decorators.ts
+const SWAGGER_KEYS = {
+	OPERATION: Symbol("kick:swagger:operation"),
+	RESPONSES: Symbol("kick:swagger:responses"),
+	TAGS: Symbol("kick:swagger:tags"),
+	BEARER_AUTH: Symbol("kick:swagger:bearer"),
+	EXCLUDE: Symbol("kick:swagger:exclude")
+};
+/** Attach operation metadata to a route handler */
+function ApiOperation(options) {
+	return (target, propertyKey) => {
+		setMethodMeta(SWAGGER_KEYS.OPERATION, options, target.constructor, propertyKey);
+	};
+}
+/** Document a response status. Can be stacked multiple times. */
+function ApiResponse(options) {
+	return (target, propertyKey) => {
+		pushMethodMeta(SWAGGER_KEYS.RESPONSES, target.constructor, propertyKey, options);
+	};
+}
+/** Apply OpenAPI tags at class or method level */
+function ApiTags(...tags) {
+	return (target, propertyKey) => {
+		if (propertyKey) setMethodMeta(SWAGGER_KEYS.TAGS, tags, target.constructor, propertyKey);
+		else setClassMeta(SWAGGER_KEYS.TAGS, tags, target);
+	};
+}
+/** Mark endpoint as requiring Bearer token auth */
+function ApiBearerAuth(name = "BearerAuth") {
+	return (target, propertyKey) => {
+		if (propertyKey) setMethodMeta(SWAGGER_KEYS.BEARER_AUTH, name, target.constructor, propertyKey);
+		else setClassMeta(SWAGGER_KEYS.BEARER_AUTH, name, target);
+	};
+}
+/** Exclude a controller or method from the OpenAPI spec */
+function ApiExclude() {
+	return (target, propertyKey) => {
+		if (propertyKey) setMethodMeta(SWAGGER_KEYS.EXCLUDE, true, target.constructor, propertyKey);
+		else setClassMeta(SWAGGER_KEYS.EXCLUDE, true, target);
+	};
+}
+//#endregion
+//#region src/openapi-builder.ts
+const registeredRoutes = [];
+/** Register a controller for OpenAPI introspection (called by Application during route mounting) */
+function registerControllerForDocs(controllerClass, mountPath) {
+	registeredRoutes.push({
+		controllerClass,
+		mountPath
+	});
+}
+/** Clear all registered routes (for HMR) */
+function clearRegisteredRoutes() {
+	registeredRoutes.length = 0;
+}
+/** Build a full OpenAPI 3.0.3 spec from registered controllers and their decorators */
+function buildOpenAPISpec(options = {}) {
+	const parser = options.schemaParser ?? zodSchemaParser;
+	/** Convert a validation schema to JSON Schema using the configured parser */
+	const toJsonSchema = (schema) => {
+		try {
+			if (!parser.supports(schema)) return null;
+			return parser.toJsonSchema(schema);
+		} catch {
+			return null;
+		}
+	};
+	const componentSchemas = {};
+	let schemaCounter = 0;
+	/**
+	* Register a schema in components.schemas and return a $ref pointer.
+	* If the schema has a title/label, use that as the name. Otherwise generate one.
+	*/
+	const registerSchema = (jsonSchema, hint) => {
+		let name = jsonSchema.title || jsonSchema.label || hint || "";
+		if (!name) name = `Schema${++schemaCounter}`;
+		name = name.replace(/[^a-zA-Z0-9]/g, "");
+		if (!componentSchemas[name]) {
+			const clean = { ...jsonSchema };
+			delete clean.title;
+			delete clean.label;
+			delete clean.$schema;
+			componentSchemas[name] = clean;
+		}
+		return { $ref: `#/components/schemas/${name}` };
+	};
+	const spec = {
+		openapi: "3.0.3",
+		info: {
+			title: options.info?.title || "API",
+			version: options.info?.version || "1.0.0",
+			...options.info?.description ? { description: options.info.description } : {}
+		},
+		paths: {},
+		components: {
+			schemas: {},
+			securitySchemes: {}
+		},
+		tags: []
+	};
+	if (options.servers) spec.servers = options.servers;
+	const allTags = /* @__PURE__ */ new Set();
+	const securitySchemes = {};
+	for (const { controllerClass, mountPath } of registeredRoutes) {
+		if (hasClassMeta(SWAGGER_KEYS.EXCLUDE, controllerClass)) continue;
+		const routes = getClassMeta(METADATA.ROUTES, controllerClass, []);
+		const classTags = getClassMeta(SWAGGER_KEYS.TAGS, controllerClass, []);
+		const classAuth = getClassMetaOrUndefined(SWAGGER_KEYS.BEARER_AUTH, controllerClass);
+		for (const route of routes) {
+			if (getMethodMetaOrUndefined(SWAGGER_KEYS.EXCLUDE, controllerClass, route.handlerName)) continue;
+			const fullPath = joinPaths(mountPath, route.path);
+			const openApiPath = fullPath.replace(/:([a-zA-Z_]+)/g, "{$1}");
+			const method = route.method.toLowerCase();
+			const operation = getMethodMeta(SWAGGER_KEYS.OPERATION, controllerClass, route.handlerName, {});
+			const responses = getMethodMeta(SWAGGER_KEYS.RESPONSES, controllerClass, route.handlerName, []);
+			const methodTags = getMethodMeta(SWAGGER_KEYS.TAGS, controllerClass, route.handlerName, []);
+			const methodAuth = getMethodMetaOrUndefined(SWAGGER_KEYS.BEARER_AUTH, controllerClass, route.handlerName);
+			const tags = methodTags.length > 0 ? methodTags : classTags;
+			tags.forEach((t) => allTags.add(t));
+			const op = {
+				...tags.length > 0 ? { tags } : {},
+				...operation.summary ? { summary: operation.summary } : {},
+				...operation.description ? { description: operation.description } : {},
+				...operation.operationId ? { operationId: operation.operationId } : {},
+				...operation.deprecated ? { deprecated: true } : {},
+				parameters: [],
+				responses: {}
+			};
+			const paramMatches = fullPath.match(/:([a-zA-Z_]+)/g) || [];
+			for (const match of paramMatches) {
+				const paramName = match.slice(1);
+				let schema = { type: "string" };
+				if (route.validation?.params) {
+					const jsonSchema = toJsonSchema(route.validation.params);
+					if (jsonSchema?.properties && typeof jsonSchema.properties === "object") {
+						const props = jsonSchema.properties;
+						if (props[paramName]) schema = props[paramName];
+					}
+				}
+				op.parameters.push({
+					name: paramName,
+					in: "path",
+					required: true,
+					schema
+				});
+			}
+			if (route.validation?.query) {
+				const jsonSchema = toJsonSchema(route.validation.query);
+				if (jsonSchema?.properties && typeof jsonSchema.properties === "object") {
+					const required = Array.isArray(jsonSchema.required) ? jsonSchema.required : [];
+					for (const [name, propSchema] of Object.entries(jsonSchema.properties)) op.parameters.push({
+						name,
+						in: "query",
+						required: required.includes(name),
+						schema: propSchema
+					});
+				}
+			}
+			const queryParamsConfig = getMethodMetaOrUndefined(METADATA.QUERY_PARAMS, controllerClass, route.handlerName);
+			if (queryParamsConfig) {
+				if (queryParamsConfig.filterable?.length) op.parameters.push({
+					name: "filter",
+					in: "query",
+					required: false,
+					description: `Filter fields: ${queryParamsConfig.filterable.join(", ")}. Format: \`field:operator:value\`. Operators: eq, neq, gt, gte, lt, lte, contains, starts, ends, in, between`,
+					schema: {
+						type: "array",
+						items: { type: "string" }
+					},
+					style: "form",
+					explode: true
+				});
+				if (queryParamsConfig.sortable?.length) op.parameters.push({
+					name: "sort",
+					in: "query",
+					required: false,
+					description: `Sort fields: ${queryParamsConfig.sortable.join(", ")}. Format: \`field:asc\` or \`field:desc\``,
+					schema: {
+						type: "array",
+						items: { type: "string" }
+					},
+					style: "form",
+					explode: true
+				});
+				if (queryParamsConfig.searchable?.length) op.parameters.push({
+					name: "q",
+					in: "query",
+					required: false,
+					description: `Search across: ${queryParamsConfig.searchable.join(", ")}`,
+					schema: { type: "string" }
+				});
+				op.parameters.push({
+					name: "page",
+					in: "query",
+					required: false,
+					description: "Page number (default: 1)",
+					schema: {
+						type: "integer",
+						minimum: 1,
+						default: 1
+					}
+				}, {
+					name: "limit",
+					in: "query",
+					required: false,
+					description: "Items per page (default: 20, max: 100)",
+					schema: {
+						type: "integer",
+						minimum: 1,
+						maximum: 100,
+						default: 20
+					}
+				});
+			}
+			if (op.parameters.length === 0) delete op.parameters;
+			if (route.validation?.body && [
+				"post",
+				"put",
+				"patch"
+			].includes(method)) {
+				const bodySchema = toJsonSchema(route.validation.body);
+				if (bodySchema) {
+					const ref = registerSchema(bodySchema, route.validation.name || `${route.handlerName}Body`);
+					op.requestBody = {
+						required: true,
+						content: { "application/json": { schema: ref } }
+					};
+				}
+			}
+			const fileUpload = getMethodMetaOrUndefined(METADATA.FILE_UPLOAD, controllerClass, route.handlerName);
+			if (fileUpload) {
+				const fieldName = fileUpload.fieldName ?? "file";
+				const properties = {};
+				if (fileUpload.mode === "array") properties[fieldName] = {
+					type: "array",
+					items: {
+						type: "string",
+						format: "binary"
+					}
+				};
+				else if (fileUpload.mode !== "none") properties[fieldName] = {
+					type: "string",
+					format: "binary"
+				};
+				op.requestBody = {
+					required: true,
+					content: { "multipart/form-data": { schema: {
+						type: "object",
+						properties
+					} } }
+				};
+			}
+			if (responses.length > 0) for (const resp of responses) op.responses[String(resp.status)] = {
+				description: resp.description || "",
+				...resp.schema ? (() => {
+					const converted = typeof resp.schema === "function" || typeof resp.schema === "object" ? toJsonSchema(resp.schema) : null;
+					const schemaName = resp.name || `${route.handlerName}Response${resp.status}`;
+					const finalSchema = converted ? registerSchema(converted, schemaName) : typeof resp.schema === "object" ? resp.schema : void 0;
+					return finalSchema ? { content: { "application/json": { schema: finalSchema } } } : {};
+				})() : {}
+			};
+			else {
+				const defaultStatus = method === "post" ? "201" : method === "delete" ? "204" : "200";
+				op.responses[defaultStatus] = { description: "Successful operation" };
+				if (route.validation?.body) op.responses["422"] = { description: "Validation error" };
+			}
+			const authName = methodAuth || classAuth;
+			if (authName) {
+				op.security = [{ [authName]: [] }];
+				securitySchemes[authName] = {
+					type: "http",
+					scheme: "bearer",
+					bearerFormat: "JWT"
+				};
+			}
+			if (!spec.paths[openApiPath]) spec.paths[openApiPath] = {};
+			spec.paths[openApiPath][method] = op;
+		}
+	}
+	spec.tags = Array.from(allTags).map((name) => ({ name }));
+	spec.components.securitySchemes = securitySchemes;
+	if (options.bearerAuth) {
+		if (!securitySchemes.BearerAuth) spec.components.securitySchemes.BearerAuth = {
+			type: "http",
+			scheme: "bearer",
+			bearerFormat: "JWT"
+		};
+		spec.security = [{ BearerAuth: [] }];
+	}
+	spec.components.schemas = componentSchemas;
+	if (Object.keys(spec.components.schemas).length === 0) delete spec.components.schemas;
+	if (Object.keys(spec.components.securitySchemes).length === 0) delete spec.components.securitySchemes;
+	if (Object.keys(spec.components).length === 0) delete spec.components;
+	return spec;
+}
+//#endregion
+//#region src/ui.ts
+/** Escape a string for safe HTML attribute/content interpolation */
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/**
+* Generate Swagger UI HTML using local assets from swagger-ui-dist.
+*
+* Assets are served from `/_swagger-assets/` by the adapter's Express
+* static middleware. Falls back to CDN if the local path is not provided.
+* This ensures Swagger UI works fully offline in development.
+*
+* @param specUrl - Path to the OpenAPI JSON spec (e.g., '/openapi.json')
+* @param title - Page title
+* @param assetsPath - Base path for local swagger-ui-dist assets (e.g., '/_swagger-assets')
+*/
+function swaggerUIHtml(specUrl, title = "API Docs", assetsPath) {
+	const safeTitle = escapeHtml(title);
+	const safeUrl = JSON.stringify(specUrl).replace(/</g, "\\u003c");
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${safeTitle}</title>
+  <link rel="stylesheet" href="${assetsPath ? `${assetsPath}/swagger-ui.css` : "https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"}">
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="${assetsPath ? `${assetsPath}/swagger-ui-bundle.js` : "https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"}"><\/script>
+  <script src="${assetsPath ? `${assetsPath}/swagger-ui-standalone-preset.js` : "https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"}"><\/script>
+  <script>
+    SwaggerUIBundle({
+      url: ${safeUrl},
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+      plugins: [SwaggerUIBundle.plugins.DownloadUrl],
+      layout: 'StandaloneLayout',
+    });
+  <\/script>
+</body>
+</html>`;
+}
+/**
+* Generate ReDoc HTML.
+*
+* ReDoc doesn't publish a standalone npm package suitable for local serving,
+* so it still loads from CDN. If offline support for ReDoc is needed,
+* vendor the standalone bundle into the package's public/ directory.
+*/
+function redocHtml(specUrl, title = "API Docs") {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+</head>
+<body>
+  <redoc spec-url="${escapeHtml(specUrl)}"></redoc>
+  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"><\/script>
+</body>
+</html>`;
+}
+//#endregion
+//#region src/swagger.adapter.ts
+const log = Logger.for("SwaggerAdapter");
+/**
+* Resolve the absolute path to swagger-ui-dist's static assets.
+* Uses createRequire to find it relative to this package (works with pnpm).
+*/
+function getSwaggerUiDistPath() {
+	return dirname(createRequire(import.meta.url).resolve("swagger-ui-dist/package.json"));
+}
+/**
+* Swagger adapter — auto-generates OpenAPI spec from decorators and serves docs.
+*
+* Assets are served locally from `swagger-ui-dist` (npm dependency) —
+* no CDN required, works fully offline.
+*
+* @example
+* ```ts
+* bootstrap({
+*   modules,
+*   adapters: [
+*     new SwaggerAdapter({
+*       info: { title: 'My API', version: '1.0.0' },
+*     }),
+*   ],
+* })
+* ```
+*
+* Endpoints:
+*   GET /docs         — Swagger UI (local assets, no CDN)
+*   GET /redoc        — ReDoc (CDN — no local package available)
+*   GET /openapi.json — Raw OpenAPI 3.0.3 spec
+*/
+var SwaggerAdapter = class {
+	name = "SwaggerAdapter";
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/** Auto-detect server URLs from the running HTTP server and peer adapters */
+	afterStart({ server }) {
+		const addr = server?.address?.();
+		if (!addr || typeof addr !== "object") return;
+		const host = addr.address === "::" || addr.address === "0.0.0.0" ? "localhost" : addr.address;
+		if (!this.options.servers || this.options.servers.length === 0) this.options.servers = [{
+			url: `http://${host}:${addr.port}`,
+			description: "HTTP server"
+		}];
+		const wsAdapter = this.options.adapters?.find((a) => a.name === "WsAdapter" && typeof a.getStats === "function");
+		if (wsAdapter) {
+			const stats = wsAdapter.getStats();
+			for (const namespace of Object.keys(stats.namespaces || {})) this.options.servers.push({
+				url: `ws://${host}:${addr.port}${namespace}`,
+				description: `WebSocket: ${namespace}`
+			});
+		}
+	}
+	/** Collect controller metadata as routes are mounted */
+	onRouteMount(controllerClass, mountPath) {
+		registerControllerForDocs(controllerClass, mountPath);
+	}
+	beforeMount({ app }) {
+		clearRegisteredRoutes();
+		const docsPath = this.options.docsPath ?? "/docs";
+		const redocPath = this.options.redocPath ?? "/redoc";
+		const specPath = this.options.specPath ?? "/openapi.json";
+		let uiDistAvailable = false;
+		const docsRouter = Router();
+		const swaggerAssetsPath = "/_swagger-assets";
+		try {
+			const swaggerDistDir = getSwaggerUiDistPath();
+			docsRouter.use(swaggerAssetsPath, express.static(swaggerDistDir));
+			uiDistAvailable = true;
+		} catch {
+			log.warn("swagger-ui-dist not found — Swagger UI will load from CDN (requires internet).");
+		}
+		docsRouter.use((_req, res, next) => {
+			res.setHeader("Content-Security-Policy", [
+				"default-src 'self'",
+				"script-src 'self' 'unsafe-inline' https://unpkg.com https://cdn.redoc.ly https://cdn.jsdelivr.net",
+				"style-src 'self' 'unsafe-inline' https://unpkg.com https://fonts.googleapis.com",
+				"font-src 'self' https://fonts.gstatic.com",
+				"img-src 'self' data: https://unpkg.com",
+				"connect-src 'self'"
+			].join("; "));
+			next();
+		});
+		docsRouter.get(specPath, (_req, res) => {
+			const spec = buildOpenAPISpec(this.options);
+			res.json(spec);
+		});
+		docsRouter.get(docsPath, (_req, res) => {
+			res.type("html").send(swaggerUIHtml(specPath, this.options.info?.title, uiDistAvailable ? swaggerAssetsPath : void 0));
+		});
+		docsRouter.get(redocPath, (_req, res) => {
+			res.type("html").send(redocHtml(specPath, this.options.info?.title));
+		});
+		app.use(docsRouter);
+		log.info(`Swagger UI:  ${docsPath}`);
+		log.info(`ReDoc:       ${redocPath}`);
+		log.info(`OpenAPI spec: ${specPath}`);
+	}
+};
+//#endregion
+export { ApiBearerAuth, ApiExclude, ApiOperation, ApiResponse, ApiTags, SwaggerAdapter, buildOpenAPISpec, clearRegisteredRoutes, redocHtml, registerControllerForDocs, swaggerUIHtml, zodSchemaParser };
+
+//# sourceMappingURL=index.mjs.map