@zenofolio/hyper-decor 1.0.72 → 1.0.73

package/dist/lib/openapi/collectors/class.collector.js

@@ -1,67 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectClassMetadata = collectClassMetadata;
-require("reflect-metadata");
-const constants_1 = require("../constants");
-const method_collector_1 = require("./method.collector");
-const function_util_1 = require("../../../__internals/utils/function.util");
-const metadata_registry_1 = require("../metadata.registry");
-function collectClassMetadata(target) {
-    var _a;
-    const prototype = Reflect.getPrototypeOf(target);
-    const constructor = prototype === null || prototype === void 0 ? void 0 : prototype.constructor;
-    const name = target.name || (constructor === null || constructor === void 0 ? void 0 : constructor.name) || ((_a = target === null || target === void 0 ? void 0 : target.constructor) === null || _a === void 0 ? void 0 : _a.name);
-    // Extraemos las metadata de la clase
-    let tags = Reflect.getMetadata(constants_1.TAGS, target) || [];
-    let security = Reflect.getMetadata(constants_1.SECURITY, target) || [];
-    // Invoke custom class collectors
-    metadata_registry_1.openApiRegistry.getCollectors("class").forEach(collector => {
-        const data = collector(target);
-        if (data === null || data === void 0 ? void 0 : data.tags)
-            tags = [...tags, ...data.tags];
-        if (data === null || data === void 0 ? void 0 : data.security)
-            security = [...security, ...data.security];
-    });
-    // Si no tenemos tags, intentamos inferirlos
-    if (tags.length === 0) {
-        tags.push({ name });
-    }
-    // Si no tenemos seguridad, intentamos asignar un valor predeterminado
-    if (security.length === 0) {
-        security.push({ bearerAuth: [] });
-    }
-    // Obtenemos todos los métodos de la clase
-    const methodNames = Object.getOwnPropertyNames(target.prototype || {}).filter((method) => method !== "constructor");
-    // Creamos una lista con la metadata de cada uno de los métodos
-    const methods = {};
-    methodNames.forEach((methodName) => {
-        let methodMetadata = (0, method_collector_1.collectMethodMetadata)(target.prototype, methodName);
-        // Invoke custom method collectors
-        metadata_registry_1.openApiRegistry.getCollectors("method").forEach(collector => {
-            const data = collector(target.prototype, methodName);
-            methodMetadata = Object.assign(Object.assign({}, methodMetadata), data);
-        });
-        // Si el método no tiene parámetros definidos, intentamos inferirlos
-        if (!methodMetadata.parameters || methodMetadata.parameters.length === 0) {
-            const methodParams = (0, function_util_1.extractArgsNames)(target.prototype[methodName]);
-            methodParams === null || methodParams === void 0 ? void 0 : methodParams.forEach((paramName, index) => {
-                const inferredParam = {
-                    name: paramName || `param${index}`,
-                    in: "query",
-                    required: true,
-                    schema: {
-                        type: "string",
-                    },
-                };
-                methodMetadata.parameters || (methodMetadata.parameters = []);
-                methodMetadata.parameters.push(inferredParam);
-            });
-        }
-        methods[methodName] = methodMetadata;
-    });
-    return {
-        tags,
-        security,
-        methods,
-    };
+const metadata_1 = require("../metadata");
+/**
+ * 🏢 Extracts class-level OpenAPI metadata (Tags, Security, etc.)
+ */
+function collectClassMetadata(Target) {
+    return metadata_1.SwaggerMeta.get(Target);
 }

package/dist/lib/openapi/collectors/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./class.collector";
-export * from "./method.collector";
-export * from "./param.collector";
-export * from "./schema.collector";
+export * from './class.collector';
+export * from './method.collector';
+export * from './schema.collector';

package/dist/lib/openapi/collectors/index.js

@@ -16,5 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./class.collector"), exports);
 __exportStar(require("./method.collector"), exports);
-__exportStar(require("./param.collector"), exports);
 __exportStar(require("./schema.collector"), exports);

package/dist/lib/openapi/collectors/method.collector.d.ts

@@ -1,2 +1,7 @@
+import "reflect-metadata";
 import { Operation } from '../types';
-export declare function collectMethodMetadata(target: any, methodName: string): Operation;
+import { Constructor } from '../../server/decorators/types';
+/**
+ * 🛠️ Consolidates framework metadata and OpenAPI decorators into a single Operation object.
+ */
+export declare function collectMethodMetadata(target: Constructor, propertyKey?: string): Operation | undefined;

package/dist/lib/openapi/collectors/method.collector.js

@@ -1,68 +1,101 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectMethodMetadata = collectMethodMetadata;
-const constants_1 = require("../constants");
-const param_collector_1 = require("./param.collector");
-const constants_2 = require("../../../__internals/constants");
+require("reflect-metadata");
+const metadata_1 = require("../metadata");
+const metadata_2 = require("../../server/decorators/metadata");
 const transform_registry_1 = require("../../../__internals/transform/transform.registry");
-function collectMethodMetadata(target, methodName) {
-    const methodMetadata = {};
-    // Extraemos la metadata del método
-    const summary = Reflect.getMetadata(constants_1.METHOD_SUMMARY, target, methodName);
-    const operationId = Reflect.getMetadata(constants_1.METHOD_OPERATION_ID, target, methodName);
-    const tags = Reflect.getMetadata(constants_1.METHOD_TAGS, target, methodName);
-    const security = Reflect.getMetadata(constants_1.SECURITY, target, methodName);
-    // Extraemos las respuestas del método
-    const responses = Reflect.getMetadata(constants_1.RESPONSES, target, methodName) || {};
-    // Extraemos los parámetros del método
-    const parameters = (0, param_collector_1.collectParameterMetadata)(target, methodName);
-    // Extraemos la información del cuerpo de la solicitud
-    const requestBody = {
-        description: Reflect.getMetadata(constants_1.REQUEST_BODY_DESCRIPTION, target, methodName),
-        content: Reflect.getMetadata(constants_1.REQUEST_BODY_CONTENT, target, methodName),
-    };
-    // Bridge @Body to OpenAPI
-    const hyperParams = Reflect.getMetadata(constants_2.KEY_PARAMS_PARAM, target[methodName]);
-    if (hyperParams && hyperParams.params[methodName]) {
-        const bodyParam = hyperParams.params[methodName].find(p => ['body', 'BODY', 'req'].includes(p.key));
-        if (bodyParam) {
-            const targetSchema = bodyParam.schema;
-            if (targetSchema) {
-                const bodySchema = transform_registry_1.transformRegistry.getOpenApiSchema(targetSchema);
-                if (bodySchema) {
-                    requestBody.content = requestBody.content || {};
-                    requestBody.content['application/json'] = {
-                        schema: bodySchema
-                    };
-                }
+const constants_1 = require("../../../__internals/constants");
+const schema_collector_1 = require("./schema.collector");
+/**
+ * 🛠️ Consolidates framework metadata and OpenAPI decorators into a single Operation object.
+ */
+function collectMethodMetadata(target, propertyKey) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    if (!propertyKey)
+        return undefined;
+    // 1. Get user-defined OpenAPI metadata from decorators
+    const baseOperation = metadata_1.SwaggerMeta.get(target, propertyKey);
+    // 2. Get framework metadata (params, route, etc.)
+    const hyperMeta = metadata_2.HyperMeta.get(target, propertyKey);
+    const operation = Object.assign(Object.assign({}, baseOperation), { parameters: [...(baseOperation.parameters || [])], responses: Object.assign({}, (baseOperation.responses || {})) });
+    // 3. Bridge Parameters (@Query, @Param, @Headers)
+    if ((_a = hyperMeta.params) === null || _a === void 0 ? void 0 : _a.params) {
+        hyperMeta.params.params.forEach((param) => {
+            const inType = mapParamIn(param.decorator);
+            if (!inType)
+                return; // Skip 'body' or unknown
+            const name = param.picker || param.name || param.decorator || 'param';
+            const schema = param.schema
+                ? (transform_registry_1.transformRegistry.getOpenApiSchema(param.schema) || (0, schema_collector_1.collectSchema)(param.schema))
+                : { type: 'string' };
+            // If it's an object, we might want to explode it (if it's Query/Headers)
+            // Or if it's a DTO (whole source)
+            if (schema.type === 'object' && schema.properties && (inType === 'query' || inType === 'header')) {
+                Object.entries(schema.properties).forEach(([propName, prop]) => {
+                    operation.parameters.push({
+                        name: propName,
+                        in: inType,
+                        required: true,
+                        schema: prop
+                    });
+                });
             }
-        }
+            else {
+                operation.parameters.push({
+                    name,
+                    in: inType,
+                    required: inType === 'path' ? true : undefined,
+                    schema
+                });
+            }
+        });
     }
-    // Bridging @Output / return type to OpenAPI
-    const outputSchema = Reflect.getMetadata(constants_2.KEY_OUTPUT_SCHEMA, target, methodName)
-        || Reflect.getMetadata(constants_2.DESIGN_RETURNTYPE, target, methodName);
-    if (outputSchema && outputSchema !== Object && outputSchema !== Promise) {
-        const schema = transform_registry_1.transformRegistry.getOpenApiSchema(outputSchema);
-        if (schema) {
-            responses['200'] = responses['200'] || { description: 'Success' };
-            responses['200'].content = responses['200'].content || {};
-            responses['200'].content['application/json'] = { schema };
+    // 4. Bridge Request Body (@Body)
+    const bodyParam = (_c = (_b = hyperMeta.params) === null || _b === void 0 ? void 0 : _b.params) === null || _c === void 0 ? void 0 : _c.find((p) => p.decorator === 'Body');
+    if (bodyParam && !operation.requestBody) {
+        let schema = bodyParam.schema
+            ? (transform_registry_1.transformRegistry.getOpenApiSchema(bodyParam.schema) || (0, schema_collector_1.collectSchema)(bodyParam.schema))
+            : { type: 'object' };
+        // If a specific picker was requested, wrap the schema in an object
+        if (bodyParam.picker && bodyParam.picker !== 'body') {
+            schema = {
+                type: 'object',
+                properties: {
+                    [bodyParam.picker]: schema
+                },
+                required: [bodyParam.picker]
+            };
         }
+        operation.requestBody = {
+            content: {
+                "application/json": { schema }
+            }
+        };
+    }
+    // 5. Bridge Responses (@Output)
+    const outputSchema = ((_g = (_f = (_e = (_d = baseOperation.responses) === null || _d === void 0 ? void 0 : _d["200"]) === null || _e === void 0 ? void 0 : _e.content) === null || _f === void 0 ? void 0 : _f["application/json"]) === null || _g === void 0 ? void 0 : _g.schema)
+        || hyperMeta[constants_1.KEY_OUTPUT_SCHEMA]
+        || hyperMeta.output;
+    if (outputSchema && !operation.responses["200"]) {
+        const schema = transform_registry_1.transformRegistry.getOpenApiSchema(outputSchema) || (0, schema_collector_1.collectSchema)(outputSchema);
+        operation.responses["200"] = {
+            description: "OK",
+            content: {
+                "application/json": { schema }
+            }
+        };
+    }
+    else if (Object.keys(operation.responses).length === 0) {
+        operation.responses["200"] = { description: "OK" };
+    }
+    return operation;
+}
+function mapParamIn(decorator) {
+    switch (decorator.toLowerCase()) {
+        case 'query': return 'query';
+        case 'param': return 'path';
+        case 'headers': return 'header';
+        default: return undefined;
     }
-    // Asignamos las propiedades al objeto de metadata solo si existen
-    if (summary)
-        methodMetadata.summary = summary;
-    if (operationId)
-        methodMetadata.operationId = operationId;
-    if (tags)
-        methodMetadata.tags = tags;
-    if (security)
-        methodMetadata.security = security;
-    if (responses && Object.keys(responses).length > 0)
-        methodMetadata.responses = responses;
-    if (parameters.length > 0)
-        methodMetadata.parameters = parameters;
-    if (requestBody.content)
-        methodMetadata.requestBody = requestBody;
-    return methodMetadata;
 }

package/dist/lib/openapi/collectors/schema.collector.d.ts

@@ -1,11 +1,6 @@
-import "reflect-metadata";
-import { Schema } from "../types";
+import { Schema } from '../types';
 /**
- * Collector responsible for transforming DTO classes into OpenAPI Schema objects.
- * Uses design:type and property inspection.
+ * 🔍 Extracts a basic OpenAPI schema from a DTO class.
+ * This is a fallback when no specific transformer (Zod, etc.) is registered.
  */
 export declare function collectSchema(Target: any): Schema;
-/**
- * Infer OpenAPI type from JavaScript constructor names.
- */
-export declare function inferType(constructorName: string): string;

package/dist/lib/openapi/collectors/schema.collector.js

@@ -1,37 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectSchema = collectSchema;
-exports.inferType = inferType;
-require("reflect-metadata");
 /**
- * Collector responsible for transforming DTO classes into OpenAPI Schema objects.
- * Uses design:type and property inspection.
+ * 🔍 Extracts a basic OpenAPI schema from a DTO class.
+ * This is a fallback when no specific transformer (Zod, etc.) is registered.
  */
 function collectSchema(Target) {
-    if (!Target || typeof Target !== "function") {
-        return { type: "object" };
+    if (typeof Target !== 'function') {
+        return { type: 'string' };
     }
     const schema = {
-        type: "object",
+        type: 'object',
         properties: {},
     };
-    // Note: Standard reflect-metadata has limitations for property enumeration.
-    // In a full implementation, we might use a custom decorator or 
-    // class-transformer/class-validator if available.
-    // For now, we provide the structure to be extended.
+    // Note: Standard TS reflection doesn't expose fields without decorators.
+    // However, we can try to instantiate or use metadata if available.
+    // For now, we provide a placeholder that can be extended.
+    // If it's a primitive constructor
+    if (Target === String)
+        return { type: 'string' };
+    if (Target === Number)
+        return { type: 'number' };
+    if (Target === Boolean)
+        return { type: 'boolean' };
+    if (Target === Date)
+        return { type: 'string', format: 'date-time' };
     return schema;
 }
-/**
- * Infer OpenAPI type from JavaScript constructor names.
- */
-function inferType(constructorName) {
-    const map = {
-        String: "string",
-        Number: "number",
-        Boolean: "boolean",
-        Array: "array",
-        Object: "object",
-        Date: "string", // Dates are strings in OpenAPI
-    };
-    return map[constructorName] || "string";
-}

package/dist/lib/openapi/constants.d.ts

@@ -1,3 +1,4 @@
+export declare const KEY_OPENAPI = "hyper:openapi";
 export declare const OPENAPI_VERSION = "3.0.0";
 export declare const INFO_TITLE = "openapi:info:title";
 export declare const INFO_DESCRIPTION = "openapi:info:description";

package/dist/lib/openapi/constants.js

@@ -1,7 +1,7 @@
 "use strict";
-// constants.ts
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SECURITY_OIDC = exports.SECURITY_OAUTH2 = exports.SECURITY_API_KEY = exports.COMPONENTS_SECURITY_SCHEMES = exports.COMPONENTS_PARAMETERS = exports.COMPONENTS_RESPONSES = exports.COMPONENTS_SCHEMAS = exports.COMPONENTS = exports.METHOD_TAGS = exports.METHOD_OPERATION_ID = exports.METHOD_SUMMARY = exports.METHOD_METADATA = exports.TAG_DESCRIPTION = exports.TAG_NAME = exports.TAGS = exports.SECURITY_SCHEME = exports.SECURITY = exports.RESPONSE_SCHEMA = exports.RESPONSE_CONTENT = exports.RESPONSE_DESCRIPTION = exports.RESPONSES = exports.REQUEST_BODY_CONTENT = exports.REQUEST_BODY_DESCRIPTION = exports.REQUEST_BODY = exports.PARAM_SCHEMA = exports.PARAM_DESCRIPTION = exports.PARAM_REQUIRED = exports.PARAM_IN = exports.PARAM_NAME = exports.PARAMETERS = exports.METHOD_TRACE = exports.METHOD_OPTIONS = exports.METHOD_HEAD = exports.METHOD_PATCH = exports.METHOD_DELETE = exports.METHOD_PUT = exports.METHOD_POST = exports.METHOD_GET = exports.PATHS = exports.INFO_LICENSE = exports.INFO_CONTACT = exports.INFO_TERMS_OF_SERVICE = exports.INFO_VERSION = exports.INFO_DESCRIPTION = exports.INFO_TITLE = exports.OPENAPI_VERSION = void 0;
+exports.SECURITY_OIDC = exports.SECURITY_OAUTH2 = exports.SECURITY_API_KEY = exports.COMPONENTS_SECURITY_SCHEMES = exports.COMPONENTS_PARAMETERS = exports.COMPONENTS_RESPONSES = exports.COMPONENTS_SCHEMAS = exports.COMPONENTS = exports.METHOD_TAGS = exports.METHOD_OPERATION_ID = exports.METHOD_SUMMARY = exports.METHOD_METADATA = exports.TAG_DESCRIPTION = exports.TAG_NAME = exports.TAGS = exports.SECURITY_SCHEME = exports.SECURITY = exports.RESPONSE_SCHEMA = exports.RESPONSE_CONTENT = exports.RESPONSE_DESCRIPTION = exports.RESPONSES = exports.REQUEST_BODY_CONTENT = exports.REQUEST_BODY_DESCRIPTION = exports.REQUEST_BODY = exports.PARAM_SCHEMA = exports.PARAM_DESCRIPTION = exports.PARAM_REQUIRED = exports.PARAM_IN = exports.PARAM_NAME = exports.PARAMETERS = exports.METHOD_TRACE = exports.METHOD_OPTIONS = exports.METHOD_HEAD = exports.METHOD_PATCH = exports.METHOD_DELETE = exports.METHOD_PUT = exports.METHOD_POST = exports.METHOD_GET = exports.PATHS = exports.INFO_LICENSE = exports.INFO_CONTACT = exports.INFO_TERMS_OF_SERVICE = exports.INFO_VERSION = exports.INFO_DESCRIPTION = exports.INFO_TITLE = exports.OPENAPI_VERSION = exports.KEY_OPENAPI = void 0;
+exports.KEY_OPENAPI = "hyper:openapi";
 // OpenAPI Version
 exports.OPENAPI_VERSION = "3.0.0";
 // Info Metadata (Información general sobre la API)

package/dist/lib/openapi/decorators.d.ts

@@ -0,0 +1,16 @@
+import { Tag, OpenApiResponses, OpenApiParameter, RequestBody, SecurityRequirement, Operation } from "./types";
+/**
+ * 📝 OpenAPI Decorators consolidated for better performance and clean imports.
+ */
+export declare function ApiSummary(summary: string): (target: any, propertyKey: any) => void;
+export declare function ApiDescription(description: string): (target: any, propertyKey: any) => void;
+export declare function ApiOperationId(operationId: string): (target: any, propertyKey: any) => void;
+export declare function ApiTag(options: Tag | string): (target: any, propertyKey?: any) => void;
+export declare function ApiResponse(options: OpenApiResponses): (target: any, propertyKey?: any) => void;
+export declare function ApiParameter(options: OpenApiParameter): (target: any, propertyKey: any) => void;
+export declare function ApiRequestBody(options: RequestBody): (target: any, propertyKey: any) => void;
+export declare function ApiSecurity(options: SecurityRequirement): (target: any, propertyKey?: any) => void;
+export declare function ApiBearerAuth(name?: string): (target: any, propertyKey?: any) => void;
+export declare function ApiMethod(options: Partial<Operation>): (target: any, propertyKey: any) => void;
+export declare function ApiNamespace(name: string): (target: any, propertyKey?: any) => void;
+export declare function ApiIgnore(): (target: any, propertyKey?: any) => void;

package/dist/lib/openapi/decorators.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiSummary = ApiSummary;
+exports.ApiDescription = ApiDescription;
+exports.ApiOperationId = ApiOperationId;
+exports.ApiTag = ApiTag;
+exports.ApiResponse = ApiResponse;
+exports.ApiParameter = ApiParameter;
+exports.ApiRequestBody = ApiRequestBody;
+exports.ApiSecurity = ApiSecurity;
+exports.ApiBearerAuth = ApiBearerAuth;
+exports.ApiMethod = ApiMethod;
+exports.ApiNamespace = ApiNamespace;
+exports.ApiIgnore = ApiIgnore;
+const metadata_1 = require("./metadata");
+/**
+ * 📝 OpenAPI Decorators consolidated for better performance and clean imports.
+ */
+function ApiSummary(summary) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { summary });
+    };
+}
+function ApiDescription(description) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { description });
+    };
+}
+function ApiOperationId(operationId) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { operationId });
+    };
+}
+function ApiTag(options) {
+    const tag = typeof options === 'string' ? { name: options } : options;
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const current = metadata_1.SwaggerMeta.get(target, propertyKey);
+            const tags = [...(current.tags || []), tag];
+            // Use Map to deduplicate by name
+            const uniqueTags = Array.from(new Map(tags.map(t => [t.name, t])).values());
+            metadata_1.SwaggerMeta.set(target, propertyKey, { tags: uniqueTags });
+        }
+        else {
+            const current = metadata_1.SwaggerMeta.get(target);
+            const tags = [...(current.tags || []), tag];
+            const uniqueTags = Array.from(new Map(tags.map(t => [t.name, t])).values());
+            metadata_1.SwaggerMeta.set(target, undefined, { tags: uniqueTags });
+        }
+    };
+}
+function ApiResponse(options) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { responses: options });
+    };
+}
+function ApiParameter(options) {
+    return (target, propertyKey) => {
+        const current = metadata_1.SwaggerMeta.get(target, propertyKey);
+        const parameters = [...(current.parameters || []), options];
+        metadata_1.SwaggerMeta.set(target, propertyKey, { parameters });
+    };
+}
+function ApiRequestBody(options) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { requestBody: options });
+    };
+}
+function ApiSecurity(options) {
+    return (target, propertyKey) => {
+        const current = metadata_1.SwaggerMeta.get(target, propertyKey);
+        const security = [...(current.security || []), options];
+        metadata_1.SwaggerMeta.set(target, propertyKey, { security });
+    };
+}
+function ApiBearerAuth(name = 'bearerAuth') {
+    return ApiSecurity({ [name]: [] });
+}
+function ApiMethod(options) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, options);
+    };
+}
+function ApiNamespace(name) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { namespace: name });
+    };
+}
+function ApiIgnore() {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { ignore: true });
+    };
+}

package/dist/lib/openapi/index.d.ts

@@ -1,6 +1,30 @@
-export * from "./metadata.registry";
-export * from "./constants";
-export * from "./collectors";
-export * from "./decorators";
-export * from "./helpers";
 export * from "./types";
+import { ApiBearerAuth, ApiDescription, ApiOperationId, ApiParameter, ApiRequestBody, ApiResponse, ApiSecurity, ApiSummary, ApiTag, ApiMethod, ApiNamespace, ApiIgnore } from "./decorators";
+export declare const OpenApi: {
+    Summary: typeof ApiSummary;
+    Description: typeof ApiDescription;
+    OperationId: typeof ApiOperationId;
+    Tag: typeof ApiTag;
+    Response: typeof ApiResponse;
+    Parameter: typeof ApiParameter;
+    RequestBody: typeof ApiRequestBody;
+    Security: typeof ApiSecurity;
+    BearerAuth: typeof ApiBearerAuth;
+    Method: typeof ApiMethod;
+    Namespace: typeof ApiNamespace;
+    Ignore: typeof ApiIgnore;
+};
+export { ApiBearerAuth, ApiDescription, ApiOperationId, ApiParameter, ApiRequestBody, ApiResponse, ApiSecurity, ApiSummary, ApiTag, ApiMethod, ApiNamespace, ApiIgnore, };
+import { Constructor } from "../server/decorators/types";
+import { OpenAPIDocument } from "./types";
+/**
+ * Generates an OpenAPI specification object from a HyperApp class.
+ *
+ * @param App The Root Application Class
+ * @param options Generator options
+ * @returns OpenAPI Spec Object
+ */
+export declare function getOpenAPI(App: Constructor, options?: {
+    includeNamespaces?: string[];
+    excludeNamespaces?: string[];
+}): OpenAPIDocument;

package/dist/lib/openapi/index.js

@@ -14,9 +14,123 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./metadata.registry"), exports);
-__exportStar(require("./constants"), exports);
-__exportStar(require("./collectors"), exports);
-__exportStar(require("./decorators"), exports);
-__exportStar(require("./helpers"), exports);
+exports.ApiIgnore = exports.ApiNamespace = exports.ApiMethod = exports.ApiTag = exports.ApiSummary = exports.ApiSecurity = exports.ApiResponse = exports.ApiRequestBody = exports.ApiParameter = exports.ApiOperationId = exports.ApiDescription = exports.ApiBearerAuth = exports.OpenApi = void 0;
+exports.getOpenAPI = getOpenAPI;
 __exportStar(require("./types"), exports);
+const decorators_1 = require("./decorators");
+Object.defineProperty(exports, "ApiBearerAuth", { enumerable: true, get: function () { return decorators_1.ApiBearerAuth; } });
+Object.defineProperty(exports, "ApiDescription", { enumerable: true, get: function () { return decorators_1.ApiDescription; } });
+Object.defineProperty(exports, "ApiOperationId", { enumerable: true, get: function () { return decorators_1.ApiOperationId; } });
+Object.defineProperty(exports, "ApiParameter", { enumerable: true, get: function () { return decorators_1.ApiParameter; } });
+Object.defineProperty(exports, "ApiRequestBody", { enumerable: true, get: function () { return decorators_1.ApiRequestBody; } });
+Object.defineProperty(exports, "ApiResponse", { enumerable: true, get: function () { return decorators_1.ApiResponse; } });
+Object.defineProperty(exports, "ApiSecurity", { enumerable: true, get: function () { return decorators_1.ApiSecurity; } });
+Object.defineProperty(exports, "ApiSummary", { enumerable: true, get: function () { return decorators_1.ApiSummary; } });
+Object.defineProperty(exports, "ApiTag", { enumerable: true, get: function () { return decorators_1.ApiTag; } });
+Object.defineProperty(exports, "ApiMethod", { enumerable: true, get: function () { return decorators_1.ApiMethod; } });
+Object.defineProperty(exports, "ApiNamespace", { enumerable: true, get: function () { return decorators_1.ApiNamespace; } });
+Object.defineProperty(exports, "ApiIgnore", { enumerable: true, get: function () { return decorators_1.ApiIgnore; } });
+exports.OpenApi = {
+    Summary: decorators_1.ApiSummary,
+    Description: decorators_1.ApiDescription,
+    OperationId: decorators_1.ApiOperationId,
+    Tag: decorators_1.ApiTag,
+    Response: decorators_1.ApiResponse,
+    Parameter: decorators_1.ApiParameter,
+    RequestBody: decorators_1.ApiRequestBody,
+    Security: decorators_1.ApiSecurity,
+    BearerAuth: decorators_1.ApiBearerAuth,
+    Method: decorators_1.ApiMethod,
+    Namespace: decorators_1.ApiNamespace,
+    Ignore: decorators_1.ApiIgnore,
+};
+const tree_1 = require("../tree/tree");
+const metadata_registry_1 = require("./metadata.registry");
+// --- Registration ---
+const collectors_1 = require("./collectors");
+metadata_registry_1.openApiRegistry.registerCollector("class", collectors_1.collectClassMetadata);
+metadata_registry_1.openApiRegistry.registerCollector("method", collectors_1.collectMethodMetadata);
+/**
+ * Generates an OpenAPI specification object from a HyperApp class.
+ *
+ * @param App The Root Application Class
+ * @param options Generator options
+ * @returns OpenAPI Spec Object
+ */
+function getOpenAPI(App, options = {}) {
+    const tree = (0, tree_1.getAppTree)(App);
+    const spec = {
+        openapi: "3.0.0",
+        info: {
+            title: tree.app.name || "HyperApp API",
+            version: tree.app.version || "1.0.0",
+        },
+        paths: {},
+    };
+    const processController = (ctrl, parentNamespace) => {
+        const ctrlOpenApi = ctrl.openapi;
+        if (ctrlOpenApi === null || ctrlOpenApi === void 0 ? void 0 : ctrlOpenApi.ignore)
+            return;
+        const ctrlNamespace = (ctrlOpenApi === null || ctrlOpenApi === void 0 ? void 0 : ctrlOpenApi.namespace) || parentNamespace;
+        ctrl.routes.forEach((route) => {
+            var _a, _b;
+            const routeOpenApi = route.openapi;
+            if (!routeOpenApi || routeOpenApi.ignore)
+                return;
+            const path = normalizePath(route.fullPath);
+            if (!spec.paths[path])
+                spec.paths[path] = {};
+            const methodNamespace = routeOpenApi.namespace || ctrlNamespace;
+            // Filtering logic
+            if (options.includeNamespaces && options.includeNamespaces.length > 0) {
+                if (!methodNamespace || !options.includeNamespaces.includes(methodNamespace))
+                    return;
+            }
+            if (options.excludeNamespaces && options.excludeNamespaces.length > 0) {
+                if (methodNamespace && options.excludeNamespaces.includes(methodNamespace))
+                    return;
+            }
+            // --- Merge Metadata Inheritance ---
+            const ctrlData = (ctrl.openapi || {});
+            const finalOperation = Object.assign(Object.assign(Object.assign({ responses: {} }, ctrlData), routeOpenApi), { 
+                // Merge Tags (unique by name)
+                tags: Array.from(new Map([
+                    ...(ctrlData.tags || []).map(t => [t.name, t]),
+                    ...(routeOpenApi.tags || []).map(t => [t.name, t])
+                ]).values()), 
+                // Merge Security (additive)
+                security: [
+                    ...(ctrlData.security || []),
+                    ...(routeOpenApi.security || [])
+                ] });
+            // Remove empty fields to keep spec clean
+            if (((_a = finalOperation.tags) === null || _a === void 0 ? void 0 : _a.length) === 0)
+                delete finalOperation.tags;
+            if (((_b = finalOperation.security) === null || _b === void 0 ? void 0 : _b.length) === 0)
+                delete finalOperation.security;
+            spec.paths[path] = Object.assign(Object.assign({}, spec.paths[path]), { [route.method.toLowerCase()]: finalOperation });
+        });
+        // Clean up empty paths if all methods were filtered out
+        Object.keys(spec.paths).forEach(path => {
+            if (Object.keys(spec.paths[path]).length === 0) {
+                delete spec.paths[path];
+            }
+        });
+    };
+    function normalizePath(path) {
+        let normalized = path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+        // Remove trailing slash if it's not the root path
+        if (normalized.length > 1 && normalized.endsWith('/')) {
+            normalized = normalized.slice(0, -1);
+        }
+        return normalized;
+    }
+    const processModule = (mod) => {
+        var _a;
+        const modNamespace = (_a = mod.openapi) === null || _a === void 0 ? void 0 : _a.namespace;
+        Object.values(mod.controllers).forEach(ctrl => processController(ctrl, modNamespace));
+        Object.values(mod.modules).forEach(processModule);
+    };
+    Object.values(tree.modules).forEach(processModule);
+    return spec;
+}

package/dist/lib/openapi/metadata.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 🚀 Metadata accessor for OpenAPI/Swagger documentation
+ */
+export declare const SwaggerMeta: {
+    set: (target: object, propertyKey: any, data: object) => void;
+    get: (target: object, propertyKey?: any) => object;
+};