hasancode-api-docs 1.0.0

package/dist/middleware/ApiDoc.js

@@ -0,0 +1,307 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiDoc = void 0;
+const express_1 = require("express");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const marked_1 = require("marked");
+const RouteRegistry_1 = require("../registry/RouteRegistry");
+const code_theme_1 = require("../code-theme");
+/**
+ * Main API Documentation class
+ */
+class ApiDoc {
+    constructor(config) {
+        this.DOCS_PATH = "/api-docs"; // Fixed path
+        this.clientPath = this.resolveClientPath();
+        this.config = config; // Set initial config
+        this.configReady = this.normalizeConfig(config);
+    }
+    /**
+     * Normalize configuration with defaults
+     */
+    normalizeConfig(config) {
+        // Convert description to HTML if it exists
+        if (config === null || config === void 0 ? void 0 : config.description) {
+            const html = marked_1.marked.parse(config.description.toString());
+            config.description = '<div class="md__code">' + html + "</div>";
+        }
+        this.config = Object.assign(Object.assign({}, config), { baseUrl: config.baseUrl || "http://localhost:5000", theme: Object.assign({ primaryColor: "#3b82f6", secondaryColor: "#8b5cf6", accentColor: "#10b981", backgroundColor: "#ffffff", sidebarBackgroundColor: "#1f2937", codeTheme: code_theme_1.CODE_THEMES.VITESSE_BLACK }, config.theme) });
+    }
+    /**
+     * Resolve client path
+     */
+    resolveClientPath() {
+        const possiblePaths = [
+            path.join(__dirname, "../../client/dist"),
+            path.join(__dirname, "../client/dist"),
+            path.join(__dirname, "../../../client/dist"),
+        ];
+        for (const testPath of possiblePaths) {
+            if (fs.existsSync(testPath) &&
+                fs.existsSync(path.join(testPath, "index.html"))) {
+                return testPath;
+            }
+        }
+        return path.join(__dirname, "../../client/dist");
+    }
+    /**
+     * Convert route metadata to API documentation format
+     */
+    convertRoutesToSections() {
+        const routes = RouteRegistry_1.routeRegistry.getAll();
+        const sections = [];
+        // Group routes by tags
+        const grouped = new Map();
+        const untagged = [];
+        for (const route of routes) {
+            if (route.tags && route.tags.length > 0) {
+                for (const tag of route.tags) {
+                    if (!grouped.has(tag)) {
+                        grouped.set(tag, []);
+                    }
+                    grouped.get(tag).push(route);
+                }
+            }
+            else {
+                untagged.push(route);
+            }
+        }
+        // Create sections for each tag
+        for (const [tag, tagRoutes] of grouped.entries()) {
+            sections.push({
+                name: tag.toLowerCase().replace(/\s+/g, "-"),
+                label: tag,
+                type: "GROUP",
+                items: tagRoutes.map((route) => this.convertRouteToSection(route)),
+            });
+        }
+        // Add untagged routes
+        if (untagged.length > 0) {
+            sections.push({
+                name: "other",
+                label: "Other Endpoints",
+                type: "GROUP",
+                items: untagged.map((route) => this.convertRouteToSection(route)),
+            });
+        }
+        return sections;
+    }
+    /**
+     * Convert single route to section format
+     */
+    convertRouteToSection(route) {
+        if (route === null || route === void 0 ? void 0 : route.description) {
+            const parsed = marked_1.marked.parse(route.description.toString());
+            route.description = '<div class="md__code">' + parsed + "</div>";
+        }
+        if (route === null || route === void 0 ? void 0 : route.summary) {
+            const parsed = marked_1.marked.parse(route.summary.toString());
+            route.summary = '<div class="md__code">' + parsed + "</div>";
+        }
+        if (route === null || route === void 0 ? void 0 : route.note) {
+            const parsed = marked_1.marked.parse(route.note.toString());
+            route.note = '<div class="md__code">' + parsed + "</div>";
+        }
+        const section = {
+            name: `${route.method}${route.path}`
+                .replace(/[/:]/g, "-")
+                .replace("--", "-"),
+            label: `${route.method.toUpperCase()} ${route.path}`,
+            type: "ITEM",
+            content: route.description,
+            api: {
+                method: route.method,
+                path: route.path,
+                summary: route.summary,
+                description: route.description,
+                deprecated: route.deprecated,
+                note: route.note,
+                tags: route.tags,
+                auth: route.auth,
+            },
+        };
+        if (route.params && route.params.length > 0) {
+            section.api.params = route.params;
+        }
+        if (route.query && route.query.length > 0) {
+            section.api.query = route.query;
+        }
+        if (route.headers && route.headers.length > 0) {
+            section.api.headers = route.headers;
+        }
+        if (route.body) {
+            section.api.body = {
+                contentType: route.body.contentType,
+                required: route.body.required,
+                description: route.body.description,
+                schema: route.body.schema,
+                example: route.body.example,
+            };
+        }
+        if (route.responses && route.responses.length > 0) {
+            section.api.responses = {};
+            for (const response of route.responses) {
+                section.api.responses[response.statusCode] = {
+                    description: response.description,
+                    contentType: response.contentType,
+                    schema: response.schema,
+                    example: response.example,
+                };
+            }
+        }
+        return section;
+    }
+    /**
+     * Get Express middleware - automatically mounts at /api-docs
+     * Usage: app.use(apiDoc.middleware())
+     */
+    middleware() {
+        const router = (0, express_1.Router)();
+        router.get(`${this.DOCS_PATH}/config.json`, this.serveConfig.bind(this));
+        router.use(`${this.DOCS_PATH}/assets`, (0, express_1.static)(path.join(this.clientPath, "assets"), {
+            maxAge: "1d",
+            etag: true,
+            fallthrough: false,
+            setHeaders: (res, path) => {
+                if (path.endsWith(".js")) {
+                    res.setHeader("Content-Type", "application/javascript");
+                }
+                else if (path.endsWith(".css")) {
+                    res.setHeader("Content-Type", "text/css");
+                }
+            },
+        }));
+        router.use(this.serveApp.bind(this));
+        return router;
+    }
+    /**
+     * Serve configuration
+     */
+    serveConfig(req, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Wait for config to be ready
+            yield this.configReady;
+            // Auto-generate sections from decorated routes
+            const sections = this.convertRoutesToSections();
+            const runtimeConfig = {
+                config: Object.assign(Object.assign({}, this.config), { sections }),
+                basePath: this.DOCS_PATH,
+            };
+            res.json(runtimeConfig);
+        });
+    }
+    /**
+     * Serve the React app
+     */
+    serveApp(req, res) {
+        const indexPath = path.join(this.clientPath, "index.html");
+        if (fs.existsSync(indexPath)) {
+            let html = fs.readFileSync(indexPath, "utf-8");
+            // Inject base tag with trailing slash for proper asset resolution
+            const baseTag = `<base href="${this.DOCS_PATH}/">`;
+            // Insert base tag right after <head> or before any other tags
+            if (html.includes("<base")) {
+                // Replace existing base tag
+                html = html.replace(/<base[^>]*>/i, baseTag);
+            }
+            else {
+                // Insert new base tag
+                html = html.replace(/<head>/i, `<head>${baseTag}`);
+            }
+            res.setHeader("Content-Type", "text/html");
+            res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
+            res.send(html);
+        }
+        else {
+            res.status(404).send(`
+        <html>
+          <head>
+            <title>API Docs - Not Built</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                max-width: 600px;
+                margin: 100px auto;
+                padding: 20px;
+                text-align: center;
+              }
+              h1 { color: #e53e3e; }
+              code {
+                background: #f7fafc;
+                padding: 2px 6px;
+                border-radius: 4px;
+              }
+            </style>
+          </head>
+          <body>
+            <h1>⚠️ Client Not Built</h1>
+            <p>Please run <code>npm run build</code> first.</p>
+            <p><small>Looking at: ${this.clientPath}</small></p>
+          </body>
+        </html>
+      `);
+        }
+    }
+    /**
+     * Get all registered routes
+     */
+    getRoutes() {
+        return RouteRegistry_1.routeRegistry.getAll();
+    }
+    /**
+     * Clear all routes (useful for testing)
+     */
+    clearRoutes() {
+        RouteRegistry_1.routeRegistry.clear();
+    }
+    /**
+     * Get the documentation path
+     */
+    getDocsPath() {
+        return this.DOCS_PATH;
+    }
+}
+exports.ApiDoc = ApiDoc;

package/dist/middleware/RouteDoc.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doc = doc;
+const RouteRegistry_1 = require("../registry/RouteRegistry");
+/**
+ * doc() — Express route middleware that registers API documentation.
+ *
+ * Two signatures:
+ *
+ * ① As a standalone middleware — method & path come from Express router:
+ *
+ *   router.post('/users', doc({ summary: 'Create user', ... }), handler);
+ *
+ * ② Wrapping the handler directly (handler runs after doc is registered):
+ *
+ *   router.post('/signin/:userType',
+ *     validateRequest(schema),
+ *     doc({ summary: 'Sign in', tags: ['Auth'], ... }, AuthControllers.signin),
+ *   );
+ */
+function doc(options, handler) {
+    let registered = false; // register once per route, not on every request
+    const middleware = (req, res, next) => {
+        var _a, _b, _c, _d;
+        if (!registered) {
+            registered = true;
+            // Express populates req.route only once the route is matched
+            // (i.e. on the first real request). We use that to get method & path.
+            const method = ((_b = (_a = req.method) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : "get");
+            // req.route.path gives us the pattern (/users/:id),
+            // NOT the actual URL — exactly what we want for docs.
+            const path = (_d = (_c = req.route) === null || _c === void 0 ? void 0 : _c.path) !== null && _d !== void 0 ? _d : req.path;
+            const routeDoc = Object.assign({ method,
+                path }, options);
+            console.log(routeDoc);
+            RouteRegistry_1.routeRegistry.register(routeDoc);
+        }
+        // If the user passed a handler as second arg, call it directly
+        if (handler) {
+            return handler(req, res, next);
+        }
+        next();
+    };
+    // Mark this middleware so ApiDoc can identify it if needed
+    middleware.__isDocMiddleware = true;
+    return middleware;
+}

package/dist/registry/RouteRegistry.d.ts

@@ -0,0 +1,103 @@
+import "reflect-metadata";
+/**
+ * Metadata keys for decorator information
+ */
+export declare const MetadataKeys: {
+    ROUTE: string;
+    METHOD: string;
+    PATH: string;
+    SUMMARY: string;
+    DESCRIPTION: string;
+    TAGS: string;
+    DEPRECATED: string;
+    PARAMS: string;
+    QUERY: string;
+    BODY: string;
+    HEADERS: string;
+    RESPONSES: string;
+    AUTH: string;
+};
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+/**
+ * Route metadata structure
+ */
+export interface RouteMetadata {
+    method: HttpMethod;
+    path: string;
+    summary?: string;
+    note?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    params?: ParamMetadata[];
+    query?: ParamMetadata[];
+    body?: BodyMetadata;
+    headers?: ParamMetadata[];
+    responses?: ResponseMetadata[];
+    auth?: boolean | AuthMetadata;
+}
+export interface ParamMetadata {
+    name: string;
+    type: "string" | "number" | "boolean" | "object" | "array";
+    required?: boolean;
+    description?: string;
+    example?: any;
+    default?: any;
+    enum?: any[];
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+}
+export interface BodyMetadata {
+    contentType?: string;
+    required?: boolean;
+    description?: string;
+    schema: Record<string, ParamMetadata>;
+    example?: any;
+}
+export interface ResponseMetadata {
+    statusCode: number;
+    description: string;
+    contentType?: string;
+    schema?: Record<string, ParamMetadata>;
+    example?: any;
+}
+export interface AuthMetadata {
+    required: boolean;
+    type?: "Bearer" | "Basic" | "ApiKey";
+    scopes?: string[];
+}
+/**
+ * Global route registry
+ */
+declare class RouteRegistry {
+    private routes;
+    /**
+     * Generate unique key using method + path
+     */
+    private generateKey;
+    /**
+     * Register a route
+     */
+    register(metadata: RouteMetadata): void;
+    /**
+     * Get a specific route
+     */
+    get(method: HttpMethod, path: string): RouteMetadata | undefined;
+    /**
+     * Get all registered routes
+     */
+    getAll(): RouteMetadata[];
+    /**
+     * Clear all routes (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get routes by tag
+     */
+    getByTag(tag: string): RouteMetadata[];
+}
+export declare const routeRegistry: RouteRegistry;
+export {};

package/dist/registry/RouteRegistry.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeRegistry = exports.MetadataKeys = void 0;
+require("reflect-metadata");
+/**
+ * Metadata keys for decorator information
+ */
+exports.MetadataKeys = {
+    ROUTE: "api:route",
+    METHOD: "api:method",
+    PATH: "api:path",
+    SUMMARY: "api:summary",
+    DESCRIPTION: "api:description",
+    TAGS: "api:tags",
+    DEPRECATED: "api:deprecated",
+    PARAMS: "api:params",
+    QUERY: "api:query",
+    BODY: "api:body",
+    HEADERS: "api:headers",
+    RESPONSES: "api:responses",
+    AUTH: "api:auth",
+};
+/**
+ * Global route registry
+ */
+class RouteRegistry {
+    constructor() {
+        this.routes = new Map();
+    }
+    /**
+     * Generate unique key using method + path
+     */
+    generateKey(metadata) {
+        return `${metadata.method.toUpperCase()}.${metadata.path}`;
+    }
+    /**
+     * Register a route
+     */
+    register(metadata) {
+        const key = this.generateKey(metadata);
+        this.routes.set(key, metadata);
+    }
+    /**
+     * Get a specific route
+     */
+    get(method, path) {
+        const key = `${method.toUpperCase()}.${path}`;
+        return this.routes.get(key);
+    }
+    /**
+     * Get all registered routes
+     */
+    getAll() {
+        return Array.from(this.routes.values());
+    }
+    /**
+     * Clear all routes (useful for testing)
+     */
+    clear() {
+        this.routes.clear();
+    }
+    /**
+     * Get routes by tag
+     */
+    getByTag(tag) {
+        return this.getAll().filter((route) => route.tags && route.tags.includes(tag));
+    }
+}
+// Singleton instance
+exports.routeRegistry = new RouteRegistry();

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "hasancode-api-docs",
+    "version": "1.0.0",
+    "description": "A simple and easy to use API documentation generator for Express.js",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc && cd client && tsc -b && vite build",
+        "prepublishOnly": "npm run build"
+    },
+    "files": [
+        "dist/",
+        "client/dist/",
+        "README.md",
+        "LICENSE"
+    ],
+    "keywords": [
+        "api",
+        "documentation",
+        "express",
+        "typescript",
+        "decorators",
+        "swagger",
+        "openapi",
+        "auto-generate"
+    ],
+    "author": "Mehedi Hasan <mehedi01616720009@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Mehedi01616720009/api-docs.git"
+    },
+    "homepage": "https://github.com/Mehedi01616720009/api-docs#readme",
+    "bugs": {
+        "url": "https://github.com/Mehedi01616720009/api-docs/issues"
+    },
+    "type": "commonjs",
+    "devDependencies": {
+        "@types/express": "^5.0.6",
+        "@types/node": "^25.2.3",
+        "typescript": "^5.9.3"
+    },
+    "dependencies": {
+        "express": "^4.0.0",
+        "fs": "^0.0.1-security",
+        "marked": "^17.0.2",
+        "reflect-metadata": "^0.2.2"
+    },
+    "peerDependencies": {
+        "express": "^4.0.0"
+    },
+    "engines": {
+        "node": ">=20.0.0"
+    }
+}