@zenofolio/hyper-decor 1.0.4 → 1.0.8

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

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectMethodMetadata = collectMethodMetadata;
+require("reflect-metadata");
+const metadata_1 = require("../metadata");
+const metadata_2 = require("../../server/decorators/metadata");
+const transform_registry_1 = require("../../../__internals/transform/transform.registry");
+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
+                });
+            }
+        });
+    }
+    // 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;
+    }
+}

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

@@ -0,0 +1,6 @@
+import { Schema } from '../types';
+/**
+ * 🔍 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;

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

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSchema = collectSchema;
+/**
+ * 🔍 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 (typeof Target !== 'function') {
+        return { type: 'string' };
+    }
+    const schema = {
+        type: 'object',
+        properties: {},
+    };
+    // 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;
+}

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

@@ -0,0 +1,47 @@
+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";
+export declare const INFO_VERSION = "openapi:info:version";
+export declare const INFO_TERMS_OF_SERVICE = "openapi:info:termsOfService";
+export declare const INFO_CONTACT = "openapi:info:contact";
+export declare const INFO_LICENSE = "openapi:info:license";
+export declare const PATHS = "openapi:paths";
+export declare const METHOD_GET = "openapi:method:get";
+export declare const METHOD_POST = "openapi:method:post";
+export declare const METHOD_PUT = "openapi:method:put";
+export declare const METHOD_DELETE = "openapi:method:delete";
+export declare const METHOD_PATCH = "openapi:method:patch";
+export declare const METHOD_HEAD = "openapi:method:head";
+export declare const METHOD_OPTIONS = "openapi:method:options";
+export declare const METHOD_TRACE = "openapi:method:trace";
+export declare const PARAMETERS = "openapi:parameters";
+export declare const PARAM_NAME = "openapi:parameter:name";
+export declare const PARAM_IN = "openapi:parameter:in";
+export declare const PARAM_REQUIRED = "openapi:parameter:required";
+export declare const PARAM_DESCRIPTION = "openapi:parameter:description";
+export declare const PARAM_SCHEMA = "openapi:parameter:schema";
+export declare const REQUEST_BODY = "openapi:requestBody";
+export declare const REQUEST_BODY_DESCRIPTION = "openapi:requestBody:description";
+export declare const REQUEST_BODY_CONTENT = "openapi:requestBody:content";
+export declare const RESPONSES = "openapi:responses";
+export declare const RESPONSE_DESCRIPTION = "openapi:response:description";
+export declare const RESPONSE_CONTENT = "openapi:response:content";
+export declare const RESPONSE_SCHEMA = "openapi:response:schema";
+export declare const SECURITY = "openapi:security";
+export declare const SECURITY_SCHEME = "openapi:security:scheme";
+export declare const TAGS = "openapi:tags";
+export declare const TAG_NAME = "openapi:tag:name";
+export declare const TAG_DESCRIPTION = "openapi:tag:description";
+export declare const METHOD_METADATA = "openapi:method:metadata";
+export declare const METHOD_SUMMARY = "openapi:method:summary";
+export declare const METHOD_OPERATION_ID = "openapi:method:operationId";
+export declare const METHOD_TAGS = "openapi:method:tags";
+export declare const COMPONENTS = "openapi:components";
+export declare const COMPONENTS_SCHEMAS = "openapi:components:schemas";
+export declare const COMPONENTS_RESPONSES = "openapi:components:responses";
+export declare const COMPONENTS_PARAMETERS = "openapi:components:parameters";
+export declare const COMPONENTS_SECURITY_SCHEMES = "openapi:components:securitySchemes";
+export declare const SECURITY_API_KEY = "openapi:security:apiKey";
+export declare const SECURITY_OAUTH2 = "openapi:security:oauth2";
+export declare const SECURITY_OIDC = "openapi:security:oidc";

package/dist/lib/openapi/constants.js

@@ -0,0 +1,61 @@
+"use strict";
+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 = 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)
+exports.INFO_TITLE = "openapi:info:title";
+exports.INFO_DESCRIPTION = "openapi:info:description";
+exports.INFO_VERSION = "openapi:info:version";
+exports.INFO_TERMS_OF_SERVICE = "openapi:info:termsOfService";
+exports.INFO_CONTACT = "openapi:info:contact";
+exports.INFO_LICENSE = "openapi:info:license";
+// Paths (Rutas de la API)
+exports.PATHS = "openapi:paths";
+exports.METHOD_GET = "openapi:method:get";
+exports.METHOD_POST = "openapi:method:post";
+exports.METHOD_PUT = "openapi:method:put";
+exports.METHOD_DELETE = "openapi:method:delete";
+exports.METHOD_PATCH = "openapi:method:patch";
+exports.METHOD_HEAD = "openapi:method:head";
+exports.METHOD_OPTIONS = "openapi:method:options";
+exports.METHOD_TRACE = "openapi:method:trace";
+// Parameters (Parámetros de los métodos)
+exports.PARAMETERS = "openapi:parameters";
+exports.PARAM_NAME = "openapi:parameter:name";
+exports.PARAM_IN = "openapi:parameter:in"; // query, header, path, cookie
+exports.PARAM_REQUIRED = "openapi:parameter:required";
+exports.PARAM_DESCRIPTION = "openapi:parameter:description";
+exports.PARAM_SCHEMA = "openapi:parameter:schema";
+// RequestBody (Cuerpo de la solicitud)
+exports.REQUEST_BODY = "openapi:requestBody";
+exports.REQUEST_BODY_DESCRIPTION = "openapi:requestBody:description";
+exports.REQUEST_BODY_CONTENT = "openapi:requestBody:content";
+// Responses (Respuestas de los métodos)
+exports.RESPONSES = "openapi:responses";
+exports.RESPONSE_DESCRIPTION = "openapi:response:description";
+exports.RESPONSE_CONTENT = "openapi:response:content";
+exports.RESPONSE_SCHEMA = "openapi:response:schema";
+// Security (Esquemas de seguridad)
+exports.SECURITY = "openapi:security";
+exports.SECURITY_SCHEME = "openapi:security:scheme"; // Esquemas de seguridad como apiKey, oauth2, etc.
+// Tags (Etiquetas de los métodos)
+exports.TAGS = "openapi:tags";
+exports.TAG_NAME = "openapi:tag:name";
+exports.TAG_DESCRIPTION = "openapi:tag:description";
+// Method Metadata (Metadatos adicionales de los métodos)
+exports.METHOD_METADATA = "openapi:method:metadata";
+exports.METHOD_SUMMARY = "openapi:method:summary";
+exports.METHOD_OPERATION_ID = "openapi:method:operationId";
+exports.METHOD_TAGS = "openapi:method:tags";
+// Components (Componentes reutilizables)
+exports.COMPONENTS = "openapi:components";
+exports.COMPONENTS_SCHEMAS = "openapi:components:schemas"; // Esquemas reutilizables de parámetros y respuestas
+exports.COMPONENTS_RESPONSES = "openapi:components:responses"; // Respuestas reutilizables
+exports.COMPONENTS_PARAMETERS = "openapi:components:parameters"; // Parámetros reutilizables
+exports.COMPONENTS_SECURITY_SCHEMES = "openapi:components:securitySchemes"; // Esquemas de seguridad reutilizables
+// Security Schemes (Esquemas de seguridad)
+exports.SECURITY_API_KEY = "openapi:security:apiKey";
+exports.SECURITY_OAUTH2 = "openapi:security:oauth2";
+exports.SECURITY_OIDC = "openapi:security:oidc"; // OpenID Connect

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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,136 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+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;
+};

package/dist/lib/openapi/metadata.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerMeta = void 0;
+const meta_store_1 = require("../../__internals/stores/meta.store");
+/**
+ * 🚀 Metadata accessor for OpenAPI/Swagger documentation
+ */
+exports.SwaggerMeta = meta_store_1.Metadata.prefix('hyper:openapi');

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

@@ -0,0 +1,29 @@
+import { AppTree } from "../tree/tree";
+export type CollectorType = "class" | "method" | "param";
+export type CollectorFn = (target: any, propertyKey?: string) => any;
+export type TreeProcessorFn = (tree: AppTree) => void;
+declare class OpenAPIMetadataRegistry {
+    private collectors;
+    private processors;
+    /**
+     * Register a custom metadata collector.
+     * @param type The level where the collector operates.
+     * @param collector The function that extracts metadata.
+     */
+    registerCollector(type: CollectorType, collector: CollectorFn): void;
+    /**
+     * Register a processor to transform the final AppTree.
+     * @param processor The function that enriches the tree.
+     */
+    registerProcessor(processor: TreeProcessorFn): void;
+    /**
+     * Returns all registered collectors for a specific type.
+     */
+    getCollectors(type: CollectorType): CollectorFn[];
+    /**
+     * Returns all registered tree processors.
+     */
+    getProcessors(): TreeProcessorFn[];
+}
+export declare const openApiRegistry: OpenAPIMetadataRegistry;
+export {};

package/dist/lib/openapi/metadata.registry.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openApiRegistry = void 0;
+class OpenAPIMetadataRegistry {
+    constructor() {
+        this.collectors = {
+            class: new Set(),
+            method: new Set(),
+            param: new Set(),
+        };
+        this.processors = new Set();
+    }
+    /**
+     * Register a custom metadata collector.
+     * @param type The level where the collector operates.
+     * @param collector The function that extracts metadata.
+     */
+    registerCollector(type, collector) {
+        this.collectors[type].add(collector);
+    }
+    /**
+     * Register a processor to transform the final AppTree.
+     * @param processor The function that enriches the tree.
+     */
+    registerProcessor(processor) {
+        this.processors.add(processor);
+    }
+    /**
+     * Returns all registered collectors for a specific type.
+     */
+    getCollectors(type) {
+        return Array.from(this.collectors[type]);
+    }
+    /**
+     * Returns all registered tree processors.
+     */
+    getProcessors() {
+        return Array.from(this.processors);
+    }
+}
+exports.openApiRegistry = new OpenAPIMetadataRegistry();