hasancode-api-docs 1.0.4 → 1.0.8

package/README.md

@@ -41,7 +41,7 @@ If you use TypeScript decorators, enable these in your `tsconfig.json`:
 
 ```ts
 import express from "express";
-import { ApiDoc, doc } from "api-docs";
+import { ApiDoc, doc } from "hasancode-api-docs";
 
 const app = express();
 app.use(express.json());
@@ -82,7 +82,7 @@ app.listen(5000, () => {
 This is the lightweight style (similar to `example/server.js`).
 
 ```ts
-import { doc } from "api-docs";
+import { doc } from "hasancode-api-docs";
 
 doc({
     method: "get",
@@ -120,7 +120,7 @@ doc({
 This is the advanced object-schema style (similar to `example2/src/app.ts`).
 
 ```ts
-import { doc } from "api-docs";
+import { doc } from "hasancode-api-docs";
 
 doc({
     method: "patch",
@@ -219,7 +219,7 @@ import {
     Description,
     Tags,
     Auth,
-} from "api-docs";
+} from "hasancode-api-docs";
 
 class UserController {
     @Tags("Users")
@@ -359,7 +359,7 @@ new ApiDoc({
 Import and use `CODE_THEMES`:
 
 ```ts
-import { CODE_THEMES } from "api-docs";
+import { CODE_THEMES } from "hasancode-api-docs";
 
 const apiDocs = new ApiDoc({
     title: "My API",

package/dist/middleware/ApiDoc.d.ts

@@ -1,9 +1,6 @@
 import { Router } from "express";
 import { RouteMetadata } from "../registry/RouteRegistry";
 import { CodeThemeValues } from "../code-theme";
-/**
- * API Documentation configuration
- */
 export interface ApiDocConfig {
     title: string;
     version: string;
@@ -22,54 +19,20 @@ export interface ApiDocConfig {
         bearerFormat?: string;
     };
 }
-/**
- * Main API Documentation class
- */
 export declare class ApiDoc {
     private config;
     private clientPath;
     private readonly DOCS_PATH;
     private configReady;
     constructor(config: ApiDocConfig);
-    /**
-     * Normalize configuration with defaults
-     */
     private normalizeConfig;
-    /**
-     * Resolve client path
-     */
     private resolveClientPath;
-    /**
-     * Convert route metadata to API documentation format
-     */
     private convertRoutesToSections;
-    /**
-     * Convert single route to section format
-     */
     private convertRouteToSection;
-    /**
-     * Get Express middleware - automatically mounts at /api-docs
-     * Usage: app.use(apiDoc.middleware())
-     */
     middleware(): Router;
-    /**
-     * Serve configuration
-     */
     private serveConfig;
-    /**
-     * Serve the React app
-     */
     private serveApp;
-    /**
-     * Get all registered routes
-     */
     getRoutes(): RouteMetadata[];
-    /**
-     * Clear all routes (useful for testing)
-     */
     clearRoutes(): void;
-    /**
-     * Get the documentation path
-     */
     getDocsPath(): string;
 }

package/dist/middleware/ApiDoc.js

@@ -49,30 +49,23 @@ 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.DOCS_PATH = "/api-docs";
         this.clientPath = this.resolveClientPath();
-        this.config = config; // Set initial config
+        this.config = 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) });
+        return __awaiter(this, void 0, void 0, function* () {
+            // Convert description to HTML if it exists
+            if (config === null || config === void 0 ? void 0 : config.description) {
+                const html = yield 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"),
@@ -87,219 +80,196 @@ class ApiDoc {
         }
         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, []);
+        return __awaiter(this, void 0, void 0, function* () {
+            const routes = RouteRegistry_1.routeRegistry.getAll();
+            const sections = [];
+            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);
                     }
-                    grouped.get(tag).push(route);
+                }
+                else {
+                    untagged.push(route);
                 }
             }
-            else {
-                untagged.push(route);
+            for (const [tag, tagRoutes] of grouped.entries()) {
+                const items = yield Promise.all(tagRoutes.map((route) => this.convertRouteToSection(route)));
+                sections.push({
+                    name: tag.toLowerCase().replace(/\s+/g, "-"),
+                    label: tag,
+                    type: "GROUP",
+                    items,
+                });
             }
-        }
-        // 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;
+            if (untagged.length > 0) {
+                const items = yield Promise.all(untagged.map((route) => this.convertRouteToSection(route)));
+                sections.push({
+                    name: "other",
+                    label: "Other Endpoints",
+                    type: "GROUP",
+                    items,
+                });
+            }
+            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,
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            if (route === null || route === void 0 ? void 0 : route.description) {
+                const parsed = yield 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 = yield 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 = yield 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.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,
+            if ((_a = route.params) === null || _a === void 0 ? void 0 : _a.length)
+                section.api.params = route.params;
+            if ((_b = route.query) === null || _b === void 0 ? void 0 : _b.length)
+                section.api.query = route.query;
+            if ((_c = route.headers) === null || _c === void 0 ? void 0 : _c.length)
+                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,
                 };
             }
-        }
-        return section;
+            if ((_d = route.responses) === null || _d === void 0 ? void 0 : _d.length) {
+                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())
-     */
+    // ══════════════════════════════════════════════════════════════
+    // FIXED: Static file serving with correct MIME types
+    // ══════════════════════════════════════════════════════════════
     middleware() {
         const router = (0, express_1.Router)();
+        // ── 1. Serve config.json (MUST come before static assets) ────
         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"), {
+        // ── 2. Serve static assets (CSS, JS, etc.) ───────────────────
+        // CRITICAL: Use absolute path match to prevent wildcard route from catching it
+        router.use(`${this.DOCS_PATH}/assets`, (req, res, next) => {
+            // Manually set correct MIME types before expressStatic processes
+            const ext = path.extname(req.path).toLowerCase();
+            if (ext === ".js") {
+                res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+            }
+            else if (ext === ".css") {
+                res.setHeader("Content-Type", "text/css; charset=utf-8");
+            }
+            else if (ext === ".map") {
+                res.setHeader("Content-Type", "application/json; charset=utf-8");
+            }
+            next();
+        }, (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");
-                }
-            },
+            index: false, // Don't serve index.html from assets
+            fallthrough: false, // Return 404 if file not found
         }));
-        router.use(this.serveApp.bind(this));
+        // ── 3. Serve React app (catch-all, MUST come last) ───────────
+        router.get(`${this.DOCS_PATH}*`, 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 = {
+            const sections = yield this.convertRoutesToSections();
+            res.json({
                 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("Content-Type", "text/html; charset=utf-8");
             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>
-      `);
+                <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>Run <code>npm run build</code> first.</p>
+                    <small>Looking at: ${this.clientPath}</small>
+                </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;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "hasancode-api-docs",
-    "version": "1.0.4",
+    "version": "1.0.8",
     "description": "A simple and easy to use API documentation generator for Express.js",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -16,6 +16,8 @@
     ],
     "keywords": [
         "api",
+        "api-doc",
+        "api-docs",
         "documentation",
         "express",
         "typescript",
@@ -47,7 +49,7 @@
         "reflect-metadata": "^0.2.2"
     },
     "peerDependencies": {
-        "express": "^4.0.0"
+        "express": ">=4.0.0"
     },
     "engines": {
         "node": ">=20.0.0"