@forinda/kickjs-swagger 1.3.2 → 1.4.1-alpha.0

package/dist/decorators.d.ts

@@ -0,0 +1,33 @@
+import 'reflect-metadata';
+declare const SWAGGER_KEYS: {
+    OPERATION: symbol;
+    RESPONSES: symbol;
+    TAGS: symbol;
+    BEARER_AUTH: symbol;
+    EXCLUDE: symbol;
+};
+export { SWAGGER_KEYS };
+export interface ApiOperationOptions {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    deprecated?: boolean;
+}
+export 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 */
+export declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
+/** Document a response status. Can be stacked multiple times. */
+export declare function ApiResponse(options: ApiResponseOptions): MethodDecorator;
+/** Apply OpenAPI tags at class or method level */
+export declare function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator;
+/** Mark endpoint as requiring Bearer token auth */
+export declare function ApiBearerAuth(name?: string): ClassDecorator & MethodDecorator;
+/** Exclude a controller or method from the OpenAPI spec */
+export declare function ApiExclude(): ClassDecorator & MethodDecorator;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAA;AAEzB,QAAA,MAAM,YAAY;;;;;;CAMjB,CAAA;AAED,OAAO,EAAE,YAAY,EAAE,CAAA;AAEvB,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,0HAA0H;IAC1H,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAI1E;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CAWxE;AAED,kDAAkD;AAClD,wBAAgB,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,eAAe,CAQ3E;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,IAAI,SAAe,GAAG,cAAc,GAAG,eAAe,CAQnF;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,IAAI,cAAc,GAAG,eAAe,CAQ7D"}

package/dist/index.d.ts

@@ -1,150 +1,6 @@
-import { Express } from 'express';
-import { AppAdapter, Container } from '@forinda/kickjs-core';
-
-/**
- * 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;
-
-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;
-
-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;
-
-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.
- *
- * @example
- * ```ts
- * bootstrap({
- *   modules,
- *   adapters: [
- *     new SwaggerAdapter({
- *       info: { title: 'My API', version: '1.0.0' },
- *     }),
- *   ],
- * })
- * ```
- *
- * Endpoints:
- *   GET /docs         — Swagger UI
- *   GET /redoc        — ReDoc
- *   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: any, _container: Container): void;
-    /** Collect controller metadata as routes are mounted */
-    onRouteMount(controllerClass: any, mountPath: string): void;
-    beforeMount(app: Express, _container: Container): void;
-}
-
-/** Generate Swagger UI HTML that loads from CDN */
-declare function swaggerUIHtml(specUrl: string, title?: string): string;
-/** Generate ReDoc HTML that loads from CDN */
-declare function redocHtml(specUrl: string, title?: string): string;
-
-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 };
+export { zodSchemaParser, type SchemaParser } from './schema-parser';
+export { ApiOperation, ApiResponse, ApiTags, ApiBearerAuth, ApiExclude, type ApiOperationOptions, type ApiResponseOptions, } from './decorators';
+export { buildOpenAPISpec, registerControllerForDocs, clearRegisteredRoutes, type OpenAPIInfo, type SwaggerOptions, } from './openapi-builder';
+export { SwaggerAdapter, type SwaggerAdapterOptions } from './swagger.adapter';
+export { swaggerUIHtml, redocHtml } from './ui';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGpE,OAAO,EACL,YAAY,EACZ,WAAW,EACX,OAAO,EACP,aAAa,EACb,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAG9E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,MAAM,CAAA"}

package/dist/index.js

@@ -1,35 +1,345 @@
-var z=Object.defineProperty;var c=(e,t)=>z(e,"name",{value:t,configurable:!0});var v={name:"zod",supports(e){return e!=null&&typeof e=="object"&&typeof e.safeParse=="function"&&typeof e.toJSONSchema=="function"},toJsonSchema(e){let{$schema:t,...o}=e.toJSONSchema();return o}};import"reflect-metadata";var p={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")};function W(e){return(t,o)=>{Reflect.defineMetadata(p.OPERATION,e,t.constructor,o)}}c(W,"ApiOperation");function X(e){return(t,o)=>{let n=Reflect.getMetadata(p.RESPONSES,t.constructor,o)||[];Reflect.defineMetadata(p.RESPONSES,[...n,e],t.constructor,o)}}c(X,"ApiResponse");function Y(...e){return(t,o)=>{o?Reflect.defineMetadata(p.TAGS,e,t.constructor,o):Reflect.defineMetadata(p.TAGS,e,t)}}c(Y,"ApiTags");function Z(e="BearerAuth"){return(t,o)=>{o?Reflect.defineMetadata(p.BEARER_AUTH,e,t.constructor,o):Reflect.defineMetadata(p.BEARER_AUTH,e,t)}}c(Z,"ApiBearerAuth");function Q(){return(e,t)=>{t?Reflect.defineMetadata(p.EXCLUDE,!0,e.constructor,t):Reflect.defineMetadata(p.EXCLUDE,!0,e)}}c(Q,"ApiExclude");import"reflect-metadata";import{METADATA as x,joinPaths as V}from"@forinda/kickjs-core";var U=[];function j(e,t){U.push({controllerClass:e,mountPath:t})}c(j,"registerControllerForDocs");function M(){U.length=0}c(M,"clearRegisteredRoutes");function N(e={}){let t=e.schemaParser??v,o=c(a=>{try{return t.supports(a)?t.toJsonSchema(a):null}catch{return null}},"toJsonSchema"),n={},S=0,u=c((a,w)=>{let h=a.title||a.label||w||"";if(h||(h=`Schema${++S}`),h=h.replace(/[^a-zA-Z0-9]/g,""),!n[h]){let b={...a};delete b.title,delete b.label,delete b.$schema,n[h]=b}return{$ref:`#/components/schemas/${h}`}},"registerSchema"),r={openapi:"3.0.3",info:{title:e.info?.title||"API",version:e.info?.version||"1.0.0",...e.info?.description?{description:e.info.description}:{}},paths:{},components:{schemas:{},securitySchemes:{}},tags:[]};e.servers&&(r.servers=e.servers);let f=new Set,m={};for(let{controllerClass:a,mountPath:w}of U){if(Reflect.getMetadata(p.EXCLUDE,a))continue;let h=Reflect.getMetadata(x.ROUTES,a)||[],b=Reflect.getMetadata(p.TAGS,a)||[],L=Reflect.getMetadata(p.BEARER_AUTH,a);for(let i of h){if(Reflect.getMetadata(p.EXCLUDE,a,i.handlerName))continue;let D=V(w,i.path),q=D.replace(/:([a-zA-Z_]+)/g,"{$1}"),E=i.method.toLowerCase(),A=Reflect.getMetadata(p.OPERATION,a,i.handlerName)||{},C=Reflect.getMetadata(p.RESPONSES,a,i.handlerName)||[],H=Reflect.getMetadata(p.TAGS,a,i.handlerName)||[],G=Reflect.getMetadata(p.BEARER_AUTH,a,i.handlerName),T=H.length>0?H:b;T.forEach(s=>f.add(s));let l={...T.length>0?{tags:T}:{},...A.summary?{summary:A.summary}:{},...A.description?{description:A.description}:{},...A.operationId?{operationId:A.operationId}:{},...A.deprecated?{deprecated:!0}:{},parameters:[],responses:{}},J=D.match(/:([a-zA-Z_]+)/g)||[];for(let s of J){let d=s.slice(1),g={type:"string"};if(i.validation?.params){let y=o(i.validation.params);if(y?.properties&&typeof y.properties=="object"){let F=y.properties;F[d]&&(g=F[d])}}l.parameters.push({name:d,in:"path",required:!0,schema:g})}if(i.validation?.query){let s=o(i.validation.query);if(s?.properties&&typeof s.properties=="object"){let d=Array.isArray(s.required)?s.required:[];for(let[g,y]of Object.entries(s.properties))l.parameters.push({name:g,in:"query",required:d.includes(g),schema:y})}}let R=Reflect.getMetadata(x.QUERY_PARAMS,a,i.handlerName);if(R&&(R.filterable?.length&&l.parameters.push({name:"filter",in:"query",required:!1,description:`Filter fields: ${R.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:!0}),R.sortable?.length&&l.parameters.push({name:"sort",in:"query",required:!1,description:`Sort fields: ${R.sortable.join(", ")}. Format: \`field:asc\` or \`field:desc\``,schema:{type:"array",items:{type:"string"}},style:"form",explode:!0}),R.searchable?.length&&l.parameters.push({name:"q",in:"query",required:!1,description:`Search across: ${R.searchable.join(", ")}`,schema:{type:"string"}}),l.parameters.push({name:"page",in:"query",required:!1,description:"Page number (default: 1)",schema:{type:"integer",minimum:1,default:1}},{name:"limit",in:"query",required:!1,description:"Items per page (default: 20, max: 100)",schema:{type:"integer",minimum:1,maximum:100,default:20}})),l.parameters.length===0&&delete l.parameters,i.validation?.body&&["post","put","patch"].includes(E)){let s=o(i.validation.body);if(s){let d=i.validation.name||`${i.handlerName}Body`,g=u(s,d);l.requestBody={required:!0,content:{"application/json":{schema:g}}}}}let P=Reflect.getMetadata(x.FILE_UPLOAD,a,i.handlerName);if(P){let s=P.fieldName??"file",d={};P.mode==="array"?d[s]={type:"array",items:{type:"string",format:"binary"}}:P.mode!=="none"&&(d[s]={type:"string",format:"binary"}),l.requestBody={required:!0,content:{"multipart/form-data":{schema:{type:"object",properties:d}}}}}if(C.length>0)for(let s of C)l.responses[String(s.status)]={description:s.description||"",...s.schema?(()=>{let d=typeof s.schema=="function"||typeof s.schema=="object"?o(s.schema):null,g=s.name||`${i.handlerName}Response${s.status}`,y=d?u(d,g):typeof s.schema=="object"?s.schema:void 0;return y?{content:{"application/json":{schema:y}}}:{}})():{}};else{let s=E==="post"?"201":E==="delete"?"204":"200";l.responses[s]={description:"Successful operation"},i.validation?.body&&(l.responses[422]={description:"Validation error"})}let O=G||L;O&&(l.security=[{[O]:[]}],m[O]={type:"http",scheme:"bearer",bearerFormat:"JWT"}),r.paths[q]||(r.paths[q]={}),r.paths[q][E]=l}}return r.tags=Array.from(f).map(a=>({name:a})),r.components.securitySchemes=m,e.bearerAuth&&(m.BearerAuth||(r.components.securitySchemes.BearerAuth={type:"http",scheme:"bearer",bearerFormat:"JWT"}),r.security=[{BearerAuth:[]}]),r.components.schemas=n,Object.keys(r.components.schemas).length===0&&delete r.components.schemas,Object.keys(r.components.securitySchemes).length===0&&delete r.components.securitySchemes,Object.keys(r.components).length===0&&delete r.components,r}c(N,"buildOpenAPISpec");import{Router as K}from"express";import{Logger as ee}from"@forinda/kickjs-core";function $(e){return e.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;")}c($,"escapeHtml");function k(e,t="API Docs"){let o=$(t),n=JSON.stringify(e).replace(/</g,"\\u003c");return`<!DOCTYPE html>
+import "reflect-metadata";
+import { Logger as D, METADATA as T, joinPaths as C } from "@forinda/kickjs-core";
+import { Router as L } from "express";
+var H = {
+  name: "zod",
+  supports(e) {
+    return e != null && typeof e == "object" && typeof e.safeParse == "function" && typeof e.toJSONSchema == "function";
+  },
+  toJsonSchema(e) {
+    const { $schema: r, ...t } = e.toJSONSchema();
+    return t;
+  }
+}, i = {
+  OPERATION: /* @__PURE__ */ Symbol("kick:swagger:operation"),
+  RESPONSES: /* @__PURE__ */ Symbol("kick:swagger:responses"),
+  TAGS: /* @__PURE__ */ Symbol("kick:swagger:tags"),
+  BEARER_AUTH: /* @__PURE__ */ Symbol("kick:swagger:bearer"),
+  EXCLUDE: /* @__PURE__ */ Symbol("kick:swagger:exclude")
+};
+function Z(e) {
+  return (r, t) => {
+    Reflect.defineMetadata(i.OPERATION, e, r.constructor, t);
+  };
+}
+function Q(e) {
+  return (r, t) => {
+    const d = Reflect.getMetadata(i.RESPONSES, r.constructor, t) || [];
+    Reflect.defineMetadata(i.RESPONSES, [...d, e], r.constructor, t);
+  };
+}
+function V(...e) {
+  return (r, t) => {
+    t ? Reflect.defineMetadata(i.TAGS, e, r.constructor, t) : Reflect.defineMetadata(i.TAGS, e, r);
+  };
+}
+function K(e = "BearerAuth") {
+  return (r, t) => {
+    t ? Reflect.defineMetadata(i.BEARER_AUTH, e, r.constructor, t) : Reflect.defineMetadata(i.BEARER_AUTH, e, r);
+  };
+}
+function ee() {
+  return (e, r) => {
+    r ? Reflect.defineMetadata(i.EXCLUDE, !0, e.constructor, r) : Reflect.defineMetadata(i.EXCLUDE, !0, e);
+  };
+}
+var M = [];
+function F(e, r) {
+  M.push({
+    controllerClass: e,
+    mountPath: r
+  });
+}
+function x() {
+  M.length = 0;
+}
+function J(e = {}) {
+  const r = e.schemaParser ?? H, t = (o) => {
+    try {
+      return r.supports(o) ? r.toJsonSchema(o) : null;
+    } catch {
+      return null;
+    }
+  }, d = {};
+  let u = 0;
+  const p = (o, w) => {
+    let f = o.title || o.label || w || "";
+    if (f || (f = `Schema${++u}`), f = f.replace(/[^a-zA-Z0-9]/g, ""), !d[f]) {
+      const R = { ...o };
+      delete R.title, delete R.label, delete R.$schema, d[f] = R;
+    }
+    return { $ref: `#/components/schemas/${f}` };
+  }, a = {
+    openapi: "3.0.3",
+    info: {
+      title: e.info?.title || "API",
+      version: e.info?.version || "1.0.0",
+      ...e.info?.description ? { description: e.info.description } : {}
+    },
+    paths: {},
+    components: {
+      schemas: {},
+      securitySchemes: {}
+    },
+    tags: []
+  };
+  e.servers && (a.servers = e.servers);
+  const m = /* @__PURE__ */ new Set(), g = {};
+  for (const { controllerClass: o, mountPath: w } of M) {
+    if (Reflect.getMetadata(i.EXCLUDE, o)) continue;
+    const f = Reflect.getMetadata(T.ROUTES, o) || [], R = Reflect.getMetadata(i.TAGS, o) || [], I = Reflect.getMetadata(i.BEARER_AUTH, o);
+    for (const n of f) {
+      if (Reflect.getMetadata(i.EXCLUDE, o, n.handlerName)) continue;
+      const $ = C(w, n.path), P = $.replace(/:([a-zA-Z_]+)/g, "{$1}"), b = n.method.toLowerCase(), y = Reflect.getMetadata(i.OPERATION, o, n.handlerName) || {}, N = Reflect.getMetadata(i.RESPONSES, o, n.handlerName) || [], k = Reflect.getMetadata(i.TAGS, o, n.handlerName) || [], _ = Reflect.getMetadata(i.BEARER_AUTH, o, n.handlerName), v = k.length > 0 ? k : R;
+      v.forEach((s) => m.add(s));
+      const c = {
+        ...v.length > 0 ? { tags: v } : {},
+        ...y.summary ? { summary: y.summary } : {},
+        ...y.description ? { description: y.description } : {},
+        ...y.operationId ? { operationId: y.operationId } : {},
+        ...y.deprecated ? { deprecated: !0 } : {},
+        parameters: [],
+        responses: {}
+      }, B = $.match(/:([a-zA-Z_]+)/g) || [];
+      for (const s of B) {
+        const l = s.slice(1);
+        let A = { type: "string" };
+        if (n.validation?.params) {
+          const h = t(n.validation.params);
+          if (h?.properties && typeof h.properties == "object") {
+            const U = h.properties;
+            U[l] && (A = U[l]);
+          }
+        }
+        c.parameters.push({
+          name: l,
+          in: "path",
+          required: !0,
+          schema: A
+        });
+      }
+      if (n.validation?.query) {
+        const s = t(n.validation.query);
+        if (s?.properties && typeof s.properties == "object") {
+          const l = Array.isArray(s.required) ? s.required : [];
+          for (const [A, h] of Object.entries(s.properties)) c.parameters.push({
+            name: A,
+            in: "query",
+            required: l.includes(A),
+            schema: h
+          });
+        }
+      }
+      const S = Reflect.getMetadata(T.QUERY_PARAMS, o, n.handlerName);
+      if (S && (S.filterable?.length && c.parameters.push({
+        name: "filter",
+        in: "query",
+        required: !1,
+        description: `Filter fields: ${S.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: !0
+      }), S.sortable?.length && c.parameters.push({
+        name: "sort",
+        in: "query",
+        required: !1,
+        description: `Sort fields: ${S.sortable.join(", ")}. Format: \`field:asc\` or \`field:desc\``,
+        schema: {
+          type: "array",
+          items: { type: "string" }
+        },
+        style: "form",
+        explode: !0
+      }), S.searchable?.length && c.parameters.push({
+        name: "q",
+        in: "query",
+        required: !1,
+        description: `Search across: ${S.searchable.join(", ")}`,
+        schema: { type: "string" }
+      }), c.parameters.push({
+        name: "page",
+        in: "query",
+        required: !1,
+        description: "Page number (default: 1)",
+        schema: {
+          type: "integer",
+          minimum: 1,
+          default: 1
+        }
+      }, {
+        name: "limit",
+        in: "query",
+        required: !1,
+        description: "Items per page (default: 20, max: 100)",
+        schema: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          default: 20
+        }
+      })), c.parameters.length === 0 && delete c.parameters, n.validation?.body && [
+        "post",
+        "put",
+        "patch"
+      ].includes(b)) {
+        const s = t(n.validation.body);
+        if (s) {
+          const l = p(s, n.validation.name || `${n.handlerName}Body`);
+          c.requestBody = {
+            required: !0,
+            content: { "application/json": { schema: l } }
+          };
+        }
+      }
+      const E = Reflect.getMetadata(T.FILE_UPLOAD, o, n.handlerName);
+      if (E) {
+        const s = E.fieldName ?? "file", l = {};
+        E.mode === "array" ? l[s] = {
+          type: "array",
+          items: {
+            type: "string",
+            format: "binary"
+          }
+        } : E.mode !== "none" && (l[s] = {
+          type: "string",
+          format: "binary"
+        }), c.requestBody = {
+          required: !0,
+          content: { "multipart/form-data": { schema: {
+            type: "object",
+            properties: l
+          } } }
+        };
+      }
+      if (N.length > 0) for (const s of N) c.responses[String(s.status)] = {
+        description: s.description || "",
+        ...s.schema ? (() => {
+          const l = typeof s.schema == "function" || typeof s.schema == "object" ? t(s.schema) : null, A = s.name || `${n.handlerName}Response${s.status}`, h = l ? p(l, A) : typeof s.schema == "object" ? s.schema : void 0;
+          return h ? { content: { "application/json": { schema: h } } } : {};
+        })() : {}
+      };
+      else {
+        const s = b === "post" ? "201" : b === "delete" ? "204" : "200";
+        c.responses[s] = { description: "Successful operation" }, n.validation?.body && (c.responses[422] = { description: "Validation error" });
+      }
+      const q = _ || I;
+      q && (c.security = [{ [q]: [] }], g[q] = {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT"
+      }), a.paths[P] || (a.paths[P] = {}), a.paths[P][b] = c;
+    }
+  }
+  return a.tags = Array.from(m).map((o) => ({ name: o })), a.components.securitySchemes = g, e.bearerAuth && (g.BearerAuth || (a.components.securitySchemes.BearerAuth = {
+    type: "http",
+    scheme: "bearer",
+    bearerFormat: "JWT"
+  }), a.security = [{ BearerAuth: [] }]), a.components.schemas = d, Object.keys(a.components.schemas).length === 0 && delete a.components.schemas, Object.keys(a.components.securitySchemes).length === 0 && delete a.components.securitySchemes, Object.keys(a.components).length === 0 && delete a.components, a;
+}
+function j(e) {
+  return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function G(e, r = "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>${o}</title>
+  <title>${j(r)}</title>
   <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
 </head>
 <body>
   <div id="swagger-ui"></div>
-  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
-  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"><\/script>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"><\/script>
   <script>
     SwaggerUIBundle({
-      url: ${n},
+      url: ${JSON.stringify(e).replace(/</g, "\\u003c")},
       dom_id: '#swagger-ui',
       deepLinking: true,
       presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
       plugins: [SwaggerUIBundle.plugins.DownloadUrl],
       layout: 'StandaloneLayout',
     });
-  </script>
+  <\/script>
 </body>
-</html>`}c(k,"swaggerUIHtml");function I(e,t="API Docs"){let o=$(t),n=$(e);return`<!DOCTYPE html>
+</html>`;
+}
+function z(e, r = "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>${o}</title>
+  <title>${j(r)}</title>
 </head>
 <body>
-  <redoc spec-url="${n}"></redoc>
-  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+  <redoc spec-url="${j(e)}"></redoc>
+  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"><\/script>
 </body>
-</html>`}c(I,"redocHtml");var _=ee.for("SwaggerAdapter"),B=class{static{c(this,"SwaggerAdapter")}options;name="SwaggerAdapter";constructor(t={}){this.options=t}afterStart(t,o){let n=t?.address?.();if(!n||typeof n!="object")return;let S=n.address==="::"||n.address==="0.0.0.0"?"localhost":n.address;(!this.options.servers||this.options.servers.length===0)&&(this.options.servers=[{url:`http://${S}:${n.port}`,description:"HTTP server"}]);let u=this.options.adapters?.find(r=>r.name==="WsAdapter"&&typeof r.getStats=="function");if(u){let r=u.getStats();for(let f of Object.keys(r.namespaces||{}))this.options.servers.push({url:`ws://${S}:${n.port}${f}`,description:`WebSocket: ${f}`})}}onRouteMount(t,o){j(t,o)}beforeMount(t,o){M();let n=this.options.docsPath??"/docs",S=this.options.redocPath??"/redoc",u=this.options.specPath??"/openapi.json",r=K();r.use((f,m,a)=>{m.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("; ")),a()}),r.get(u,(f,m)=>{let a=N(this.options);m.json(a)}),r.get(n,(f,m)=>{m.type("html").send(k(u,this.options.info?.title))}),r.get(S,(f,m)=>{m.type("html").send(I(u,this.options.info?.title))}),t.use(r),_.info(`Swagger UI:  ${n}`),_.info(`ReDoc:       ${S}`),_.info(`OpenAPI spec: ${u}`)}};export{Z as ApiBearerAuth,Q as ApiExclude,W as ApiOperation,X as ApiResponse,Y as ApiTags,B as SwaggerAdapter,N as buildOpenAPISpec,M as clearRegisteredRoutes,I as redocHtml,j as registerControllerForDocs,k as swaggerUIHtml,v as zodSchemaParser};
+</html>`;
+}
+var O = D.for("SwaggerAdapter"), te = class {
+  name = "SwaggerAdapter";
+  constructor(e = {}) {
+    this.options = e;
+  }
+  afterStart(e, r) {
+    const t = e?.address?.();
+    if (!t || typeof t != "object") return;
+    const d = t.address === "::" || t.address === "0.0.0.0" ? "localhost" : t.address;
+    (!this.options.servers || this.options.servers.length === 0) && (this.options.servers = [{
+      url: `http://${d}:${t.port}`,
+      description: "HTTP server"
+    }]);
+    const u = this.options.adapters?.find((p) => p.name === "WsAdapter" && typeof p.getStats == "function");
+    if (u) {
+      const p = u.getStats();
+      for (const a of Object.keys(p.namespaces || {})) this.options.servers.push({
+        url: `ws://${d}:${t.port}${a}`,
+        description: `WebSocket: ${a}`
+      });
+    }
+  }
+  onRouteMount(e, r) {
+    F(e, r);
+  }
+  beforeMount(e, r) {
+    x();
+    const t = this.options.docsPath ?? "/docs", d = this.options.redocPath ?? "/redoc", u = this.options.specPath ?? "/openapi.json", p = L();
+    p.use((a, m, g) => {
+      m.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("; ")), g();
+    }), p.get(u, (a, m) => {
+      const g = J(this.options);
+      m.json(g);
+    }), p.get(t, (a, m) => {
+      m.type("html").send(G(u, this.options.info?.title));
+    }), p.get(d, (a, m) => {
+      m.type("html").send(z(u, this.options.info?.title));
+    }), e.use(p), O.info(`Swagger UI:  ${t}`), O.info(`ReDoc:       ${d}`), O.info(`OpenAPI spec: ${u}`);
+  }
+};
+export {
+  K as ApiBearerAuth,
+  ee as ApiExclude,
+  Z as ApiOperation,
+  Q as ApiResponse,
+  V as ApiTags,
+  te as SwaggerAdapter,
+  J as buildOpenAPISpec,
+  x as clearRegisteredRoutes,
+  z as redocHtml,
+  F as registerControllerForDocs,
+  G as swaggerUIHtml,
+  H as zodSchemaParser
+};

package/dist/openapi-builder.d.ts

@@ -0,0 +1,36 @@
+import 'reflect-metadata';
+import { type SchemaParser } from './schema-parser';
+export interface OpenAPIInfo {
+    title: string;
+    version: string;
+    description?: string;
+}
+export 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) */
+export declare function registerControllerForDocs(controllerClass: any, mountPath: string): void;
+/** Clear all registered routes (for HMR) */
+export declare function clearRegisteredRoutes(): void;
+/** Build a full OpenAPI 3.0.3 spec from registered controllers and their decorators */
+export declare function buildOpenAPISpec(options?: SwaggerOptions): any;
+//# sourceMappingURL=openapi-builder.d.ts.map

package/dist/openapi-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-builder.d.ts","sourceRoot":"","sources":["../src/openapi-builder.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAA;AAGzB,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEpE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3B,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACjD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B;AASD,oGAAoG;AACpG,wBAAgB,yBAAyB,CAAC,eAAe,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvF;AAED,4CAA4C;AAC5C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,cAAmB,GAAG,GAAG,CA6UlE"}

package/dist/schema-parser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 })
+ * ```
+ */
+export 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.
+ */
+export declare const zodSchemaParser: SchemaParser;
+//# sourceMappingURL=schema-parser.d.ts.map

package/dist/schema-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-parser.d.ts","sourceRoot":"","sources":["../src/schema-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;IAElC;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvD;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,YAgB7B,CAAA"}

package/dist/swagger.adapter.d.ts

@@ -0,0 +1,45 @@
+import type { Express } from 'express';
+import { type AppAdapter, type Container } from '@forinda/kickjs-core';
+import { registerControllerForDocs, clearRegisteredRoutes, type SwaggerOptions } from './openapi-builder';
+export 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.
+ *
+ * @example
+ * ```ts
+ * bootstrap({
+ *   modules,
+ *   adapters: [
+ *     new SwaggerAdapter({
+ *       info: { title: 'My API', version: '1.0.0' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * Endpoints:
+ *   GET /docs         — Swagger UI
+ *   GET /redoc        — ReDoc
+ *   GET /openapi.json — Raw OpenAPI 3.0.3 spec
+ */
+export 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: any, _container: Container): void;
+    /** Collect controller metadata as routes are mounted */
+    onRouteMount(controllerClass: any, mountPath: string): void;
+    beforeMount(app: Express, _container: Container): void;
+}
+export { registerControllerForDocs, clearRegisteredRoutes };
+//# sourceMappingURL=swagger.adapter.d.ts.map

package/dist/swagger.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.adapter.d.ts","sourceRoot":"","sources":["../src/swagger.adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC9E,OAAO,EAEL,yBAAyB,EACzB,qBAAqB,EACrB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAA;AAK1B,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAe,YAAW,UAAU;IAGnC,OAAO,CAAC,OAAO;IAF3B,IAAI,SAAmB;gBAEH,OAAO,GAAE,qBAA0B;IAEvD,6EAA6E;IAC7E,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,GAAG,IAAI;IA0BpD,wDAAwD;IACxD,YAAY,CAAC,eAAe,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAI3D,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,GAAG,IAAI;CA+CvD;AAGD,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,CAAA"}

package/dist/ui.d.ts

@@ -0,0 +1,5 @@
+/** Generate Swagger UI HTML that loads from CDN */
+export declare function swaggerUIHtml(specUrl: string, title?: string): string;
+/** Generate ReDoc HTML that loads from CDN */
+export declare function redocHtml(specUrl: string, title?: string): string;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAUA,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,CA4BzE;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,CAgBrE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs-swagger",
-  "version": "1.3.2",
+  "version": "1.4.1-alpha.0",
   "description": "OpenAPI spec generation from decorators, Swagger UI and ReDoc serving for KickJS",
   "keywords": [
     "kickjs",
@@ -34,7 +34,8 @@
     "@forinda/kickjs-queue",
     "@forinda/kickjs-multi-tenant",
     "@forinda/kickjs-devtools",
-    "@forinda/kickjs-notifications"
+    "@forinda/kickjs-notifications",
+    "vite"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +51,7 @@
   ],
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "@forinda/kickjs-core": "1.3.2"
+    "@forinda/kickjs-core": "1.4.1-alpha.0"
   },
   "peerDependencies": {
     "express": "^5.1.0",
@@ -64,11 +65,10 @@
   "devDependencies": {
     "@swc/core": "^1.7.28",
     "@types/express": "^5.0.6",
-    "@types/node": "^24.5.2",
+    "@types/node": "^25.0.0",
     "express": "^5.1.0",
-    "tsup": "^8.5.0",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.1",
     "zod": "^4.3.6"
   },
   "publishConfig": {
@@ -89,8 +89,9 @@
     "url": "https://github.com/forinda/kick-js/issues"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "vite build && pnpm build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "dev": "vite build --watch",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",