hasancode-api-docs 1.0.0

package/dist/decorators/ParameterDecorators.d.ts

@@ -0,0 +1,33 @@
+import { ParamMetadata } from "../registry/RouteRegistry";
+/**
+ * Path parameter decorator
+ * @example
+ * @Param('id', { type: 'string', required: true, description: 'User ID' })
+ */
+export declare function Param(name: string, config: Omit<ParamMetadata, "name">): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Query parameter decorator
+ * @example
+ * @Query('page', { type: 'number', default: 1, description: 'Page number' })
+ */
+export declare function Query(name: string, config: Omit<ParamMetadata, "name">): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Header decorator
+ * @example
+ * @Header('Authorization', { type: 'string', required: true })
+ */
+export declare function Header(name: string, config: Omit<ParamMetadata, "name">): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Request body decorator
+ * @example
+ * @Body({
+ *   email: { type: 'string', required: true },
+ *   password: { type: 'string', required: true }
+ * })
+ */
+export declare function Body(schema: Record<string, Omit<ParamMetadata, "name">>, options?: {
+    contentType?: string;
+    required?: boolean;
+    description?: string;
+    example?: any;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/dist/decorators/ParameterDecorators.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Param = Param;
+exports.Query = Query;
+exports.Header = Header;
+exports.Body = Body;
+const marked_1 = require("marked");
+const RouteRegistry_1 = require("../registry/RouteRegistry");
+/**
+ * Helper to get or create metadata for a route based on the decorator context
+ */
+function getOrCreateMetadata(target, propertyKey, defaultMethod = "get", defaultPath = "/") {
+    // Try to get method and path from existing metadata
+    const method = Reflect.getMetadata("api:method", target, propertyKey) || defaultMethod;
+    const path = Reflect.getMetadata("api:path", target, propertyKey) ||
+        defaultPath;
+    return { method, path };
+}
+/**
+ * Path parameter decorator
+ * @example
+ * @Param('id', { type: 'string', required: true, description: 'User ID' })
+ */
+function Param(name, config) {
+    return function (target, propertyKey, descriptor) {
+        const { method, path } = getOrCreateMetadata(target, propertyKey);
+        let metadata = RouteRegistry_1.routeRegistry.get(method, path);
+        if (!metadata) {
+            metadata = {
+                method,
+                path,
+                params: [],
+            };
+        }
+        if (!metadata.params) {
+            metadata.params = [];
+        }
+        // Convert description to HTML if it exists
+        if (config === null || config === void 0 ? void 0 : config.description) {
+            const paramData = Object.assign(Object.assign({ name }, config), { description: '<div class="md__code">' +
+                    marked_1.marked.parse(config.description.toString()) +
+                    "</div>" });
+            metadata.params.push(paramData);
+            RouteRegistry_1.routeRegistry.register(metadata);
+        }
+        else {
+            metadata.params.push(Object.assign({ name }, config));
+            RouteRegistry_1.routeRegistry.register(metadata);
+        }
+        return descriptor;
+    };
+}
+/**
+ * Query parameter decorator
+ * @example
+ * @Query('page', { type: 'number', default: 1, description: 'Page number' })
+ */
+function Query(name, config) {
+    return function (target, propertyKey, descriptor) {
+        const { method, path } = getOrCreateMetadata(target, propertyKey);
+        let metadata = RouteRegistry_1.routeRegistry.get(method, path);
+        if (!metadata) {
+            metadata = {
+                method,
+                path,
+                query: [],
+            };
+        }
+        if (!metadata.query) {
+            metadata.query = [];
+        }
+        // Convert description to HTML if it exists
+        if (config === null || config === void 0 ? void 0 : config.description) {
+            const queryData = Object.assign(Object.assign({ name }, config), { description: '<div class="md__code">' +
+                    marked_1.marked.parse(config.description.toString()) +
+                    "</div>" });
+            metadata.query.push(queryData);
+            RouteRegistry_1.routeRegistry.register(metadata);
+        }
+        else {
+            metadata.query.push(Object.assign({ name }, config));
+            RouteRegistry_1.routeRegistry.register(metadata);
+        }
+        return descriptor;
+    };
+}
+/**
+ * Header decorator
+ * @example
+ * @Header('Authorization', { type: 'string', required: true })
+ */
+function Header(name, config) {
+    return function (target, propertyKey, descriptor) {
+        const { method, path } = getOrCreateMetadata(target, propertyKey);
+        let metadata = RouteRegistry_1.routeRegistry.get(method, path);
+        if (!metadata) {
+            metadata = {
+                method,
+                path,
+                headers: [],
+            };
+        }
+        if (!metadata.headers) {
+            metadata.headers = [];
+        }
+        metadata.headers.push(Object.assign({ name }, config));
+        RouteRegistry_1.routeRegistry.register(metadata);
+        return descriptor;
+    };
+}
+/**
+ * Request body decorator
+ * @example
+ * @Body({
+ *   email: { type: 'string', required: true },
+ *   password: { type: 'string', required: true }
+ * })
+ */
+function Body(schema, options) {
+    return function (target, propertyKey, descriptor) {
+        const { method, path } = getOrCreateMetadata(target, propertyKey, "post");
+        let metadata = RouteRegistry_1.routeRegistry.get(method, path);
+        if (!metadata) {
+            metadata = {
+                method,
+                path,
+            };
+        }
+        // Convert schema to proper format and handle descriptions
+        const processSchema = () => {
+            const bodySchema = {};
+            for (const [name, config] of Object.entries(schema)) {
+                if (config === null || config === void 0 ? void 0 : config.description) {
+                    const html = marked_1.marked.parse(config.description);
+                    bodySchema[name] = Object.assign(Object.assign({ name }, config), { description: '<div class="md__code">' + html + "</div>" });
+                }
+                else {
+                    bodySchema[name] = Object.assign({ name }, config);
+                }
+            }
+            let bodyDescription = options === null || options === void 0 ? void 0 : options.description;
+            if (options === null || options === void 0 ? void 0 : options.description) {
+                const parsed = marked_1.marked.parse(options.description.toString());
+                bodyDescription = '<div class="md__code">' + parsed + "</div>";
+            }
+            metadata.body = {
+                contentType: (options === null || options === void 0 ? void 0 : options.contentType) || "application/json",
+                required: (options === null || options === void 0 ? void 0 : options.required) !== false,
+                description: bodyDescription,
+                schema: bodySchema,
+                example: options === null || options === void 0 ? void 0 : options.example,
+            };
+            RouteRegistry_1.routeRegistry.register(metadata);
+        };
+        processSchema();
+        return descriptor;
+    };
+}

package/dist/define/DefineDoc.d.ts

@@ -0,0 +1,39 @@
+import { RouteMetadata, ParamMetadata } from "../registry/RouteRegistry";
+/**
+ * Input type for doc() function - allows flexible input format
+ */
+export interface DocInput {
+    method: RouteMetadata["method"];
+    path: string;
+    summary?: string;
+    note?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    params?: Record<string, Omit<ParamMetadata, "name">> | ParamMetadata[];
+    query?: Record<string, Omit<ParamMetadata, "name">> | ParamMetadata[];
+    headers?: Record<string, Omit<ParamMetadata, "name">> | ParamMetadata[];
+    body?: {
+        contentType?: string;
+        required?: boolean;
+        description?: string;
+        schema: Record<string, Omit<ParamMetadata, "name">>;
+        example?: any;
+    };
+    responses?: Record<number, {
+        description: string;
+        contentType?: string;
+        schema?: Record<string, Omit<ParamMetadata, "name">>;
+        example?: any;
+    }>;
+    auth?: boolean | {
+        required: boolean;
+        type?: "Bearer" | "Basic" | "ApiKey";
+        scopes?: string[];
+    };
+}
+/**
+ * doc() — Register API documentation for ANY route.
+ * Works with modular, functional, MVC, raw Express — any structure.
+ */
+export declare function doc(docInput: DocInput): void;

package/dist/define/DefineDoc.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doc = doc;
+const marked_1 = require("marked");
+const RouteRegistry_1 = require("../registry/RouteRegistry");
+/**
+ * Helper to convert object params to array format
+ */
+function convertParamsToArray(params) {
+    if (!params)
+        return undefined;
+    // If already array, return as is
+    if (Array.isArray(params))
+        return params;
+    // Convert object to array
+    return Object.entries(params).map(([name, config]) => (Object.assign({ name }, config)));
+}
+/**
+ * Helper to convert body schema to proper format
+ */
+function convertBodySchema(body) {
+    if (!body)
+        return undefined;
+    const schema = {};
+    for (const [name, config] of Object.entries(body.schema)) {
+        schema[name] = Object.assign({ name }, config);
+    }
+    if (body === null || body === void 0 ? void 0 : body.description) {
+        const parsed = marked_1.marked.parse(body.description.toString());
+        body.description = '<div class="md__code">' + parsed + "</div>";
+    }
+    return {
+        contentType: body.contentType || "application/json",
+        required: body.required !== false,
+        description: body.description,
+        schema,
+        example: body.example,
+    };
+}
+/**
+ * Helper to convert responses object to array format
+ */
+function convertResponsesToArray(responses) {
+    if (!responses)
+        return undefined;
+    return Object.entries(responses).map(([statusCode, config]) => {
+        let responseSchema;
+        if (config.schema) {
+            responseSchema = {};
+            for (const [name, paramConfig] of Object.entries(config.schema)) {
+                responseSchema[name] = Object.assign({ name }, paramConfig);
+            }
+        }
+        let description = config.description;
+        if (description) {
+            const parsed = marked_1.marked.parse(description.toString());
+            description = `<div class="md__code">${parsed}</div>`;
+        }
+        return {
+            statusCode: parseInt(statusCode),
+            description,
+            contentType: config.contentType || "application/json",
+            schema: responseSchema,
+            example: config.example,
+        };
+    });
+}
+/**
+ * doc() — Register API documentation for ANY route.
+ * Works with modular, functional, MVC, raw Express — any structure.
+ */
+function doc(docInput) {
+    // Convert input format to RouteMetadata format
+    const metadata = {
+        method: docInput.method,
+        path: docInput.path,
+        summary: docInput.summary,
+        note: docInput.note,
+        description: docInput.description,
+        tags: docInput.tags,
+        deprecated: docInput.deprecated,
+        params: convertParamsToArray(docInput.params),
+        query: convertParamsToArray(docInput.query),
+        headers: convertParamsToArray(docInput.headers),
+        body: convertBodySchema(docInput.body),
+        responses: convertResponsesToArray(docInput.responses),
+        auth: docInput.auth,
+    };
+    RouteRegistry_1.routeRegistry.register(metadata);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import "reflect-metadata";
+export { CODE_THEMES, CodeThemeValues } from "./code-theme";
+export { ApiDoc, type ApiDocConfig } from "./middleware/ApiDoc";
+export { Get, Post, Put, Patch, Delete, Route, } from "./decorators/MethodDecorators";
+export { Param, Query, Header, Body } from "./decorators/ParameterDecorators";
+export { Response, Summary, Description, Tags, Deprecated, Auth, } from "./decorators/MetadataDecorators";
+export { doc } from "./define/DefineDoc";
+export { type RouteMetadata, type ParamMetadata, type BodyMetadata, type ResponseMetadata, type AuthMetadata, } from "./registry/RouteRegistry";

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doc = exports.Auth = exports.Deprecated = exports.Tags = exports.Description = exports.Summary = exports.Response = exports.Body = exports.Header = exports.Query = exports.Param = exports.Route = exports.Delete = exports.Patch = exports.Put = exports.Post = exports.Get = exports.ApiDoc = exports.CODE_THEMES = void 0;
+require("reflect-metadata");
+// Code theme type and constant
+var code_theme_1 = require("./code-theme");
+Object.defineProperty(exports, "CODE_THEMES", { enumerable: true, get: function () { return code_theme_1.CODE_THEMES; } });
+// Main class
+var ApiDoc_1 = require("./middleware/ApiDoc");
+Object.defineProperty(exports, "ApiDoc", { enumerable: true, get: function () { return ApiDoc_1.ApiDoc; } });
+// HTTP Method decorators
+var MethodDecorators_1 = require("./decorators/MethodDecorators");
+Object.defineProperty(exports, "Get", { enumerable: true, get: function () { return MethodDecorators_1.Get; } });
+Object.defineProperty(exports, "Post", { enumerable: true, get: function () { return MethodDecorators_1.Post; } });
+Object.defineProperty(exports, "Put", { enumerable: true, get: function () { return MethodDecorators_1.Put; } });
+Object.defineProperty(exports, "Patch", { enumerable: true, get: function () { return MethodDecorators_1.Patch; } });
+Object.defineProperty(exports, "Delete", { enumerable: true, get: function () { return MethodDecorators_1.Delete; } });
+Object.defineProperty(exports, "Route", { enumerable: true, get: function () { return MethodDecorators_1.Route; } });
+// Parameter decorators
+var ParameterDecorators_1 = require("./decorators/ParameterDecorators");
+Object.defineProperty(exports, "Param", { enumerable: true, get: function () { return ParameterDecorators_1.Param; } });
+Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return ParameterDecorators_1.Query; } });
+Object.defineProperty(exports, "Header", { enumerable: true, get: function () { return ParameterDecorators_1.Header; } });
+Object.defineProperty(exports, "Body", { enumerable: true, get: function () { return ParameterDecorators_1.Body; } });
+// Metadata decorators
+var MetadataDecorators_1 = require("./decorators/MetadataDecorators");
+Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return MetadataDecorators_1.Response; } });
+Object.defineProperty(exports, "Summary", { enumerable: true, get: function () { return MetadataDecorators_1.Summary; } });
+Object.defineProperty(exports, "Description", { enumerable: true, get: function () { return MetadataDecorators_1.Description; } });
+Object.defineProperty(exports, "Tags", { enumerable: true, get: function () { return MetadataDecorators_1.Tags; } });
+Object.defineProperty(exports, "Deprecated", { enumerable: true, get: function () { return MetadataDecorators_1.Deprecated; } });
+Object.defineProperty(exports, "Auth", { enumerable: true, get: function () { return MetadataDecorators_1.Auth; } });
+// ── For modular / functional / raw Express ────
+// doc() is an Express middleware — sits inline in router.get/post/put/delete
+// method & path are inferred automatically from the router
+var DefineDoc_1 = require("./define/DefineDoc");
+Object.defineProperty(exports, "doc", { enumerable: true, get: function () { return DefineDoc_1.doc; } });

package/dist/middleware/ApiDoc.d.ts

@@ -0,0 +1,75 @@
+import { Router } from "express";
+import { RouteMetadata } from "../registry/RouteRegistry";
+import { CodeThemeValues } from "../code-theme";
+/**
+ * API Documentation configuration
+ */
+export interface ApiDocConfig {
+    title: string;
+    version: string;
+    description?: string;
+    baseUrl?: string;
+    theme?: {
+        primaryColor?: string;
+        secondaryColor?: string;
+        accentColor?: string;
+        backgroundColor?: string;
+        sidebarBackgroundColor?: string;
+        codeTheme?: CodeThemeValues;
+    };
+    defaultAuth?: {
+        type: "Bearer" | "Basic" | "ApiKey";
+        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;
+}