@arikajs/docs 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArikaJs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+## Arika Docs
+
+`@arikajs/docs` is the **documentation engine** of the ArikaJS ecosystem.
+
+It allows you to automatically generate high-quality API documentation, Postman collections, and OpenAPI specifications by analyzing your application's routes.
+
+The goal of this package is to eliminate the manual work of keeping documentation in sync with your codebase.
+
+---
+
+### Status
+
+- **Stage**: Experimental / v0.x
+- **Scope (v0.x)**:
+  - Route metadata extraction from `@arikajs/router`
+  - Postman Collection (v2.1.0) generation
+  - Arika-themed interactive HTML documentation
+  - Markdown (DOCS.md) generation
+  - OpenAPI 3.0 specification generation
+
+---
+
+## Features
+
+- **Multi-Format Generation**
+  - **HTML**: A premium, interactive web page for your API.
+  - **Postman**: Ready-to-import JSON collection with pre-configured headers.
+  - **OpenAPI**: Industry-standard Swagger/OpenAPI 3.0 specification.
+  - **Markdown**: Clean, readable `DOCS.md` for GitHub or local documentation.
+
+- **Route Analysis**
+  - Automatically groups endpoints by prefix (e.g., `api`, `admin`).
+  - Captures route names, methods, and full path hierarchies.
+  - Displays middleware information for each endpoint.
+
+- **Environment Support**
+  - Automatically generates Postman environment JSON with your `base_url`.
+
+---
+
+## Installation
+
+```bash
+npm install @arikajs/docs
+```
+
+This package is designed to be used with the ArikaJS CLI but can also be used as a standalone library.
+
+---
+
+## Usage (via CLI)
+
+The easiest way to generate documentation is using the ArikaJS CLI:
+
+```bash
+arika docs:generate
+```
+
+This will create a `docs/` directory in your project root containing all generation artifacts.
+
+---
+
+## Standalone Usage
+
+```ts
+import { DocumentationGenerator } from '@arikajs/docs';
+
+const generator = new DocumentationGenerator();
+generator.generateAll('My App Name', './docs-output');
+```
+
+---
+
+## Project Structure
+
+Inside the `docs` package:
+
+- `src/`
+  - `PostmanGenerator.ts` – Handles Postman JSON generation
+  - `HtmlGenerator.ts` – Handles premium HTML documentation
+  - `MarkdownGenerator.ts` – Handles Markdown generation
+  - `OpenApiGenerator.ts` – Handles OpenAPI 3.0 generation
+  - `Generator.ts` – The main orchestrator
+  - `index.ts` – Public exports
+
+---
+
+## Philosophy
+
+> “Your code is the source of truth; your documentation should reflect it instantly.”
+
+---
+
+## Contributing
+
+Contributions are welcome, especially around:
+- Adding support for JSDoc-based parameter descriptions.
+- Enhancing the HTML documentation search and "Try it out" features.
+- Adding support for more documentation formats.
+
+---
+
+## License
+
+`@arikajs/docs` is open-sourced software licensed under the **MIT license**.

package/dist/Generator.d.ts

@@ -0,0 +1,12 @@
+import { PostmanGenerator } from './PostmanGenerator';
+import { MarkdownGenerator } from './MarkdownGenerator';
+import { HtmlGenerator } from './HtmlGenerator';
+import { OpenApiGenerator } from './OpenApiGenerator';
+export declare class DocumentationGenerator {
+    protected postman: PostmanGenerator;
+    protected markdown: MarkdownGenerator;
+    protected html: HtmlGenerator;
+    protected openApi: OpenApiGenerator;
+    constructor();
+    generateAll(appName: string, outputDir: string): void;
+}

package/dist/Generator.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentationGenerator = void 0;
+const router_1 = require("@arikajs/router");
+const PostmanGenerator_1 = require("./PostmanGenerator");
+const MarkdownGenerator_1 = require("./MarkdownGenerator");
+const HtmlGenerator_1 = require("./HtmlGenerator");
+const OpenApiGenerator_1 = require("./OpenApiGenerator");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+class DocumentationGenerator {
+    postman;
+    markdown;
+    html;
+    openApi;
+    constructor() {
+        this.postman = new PostmanGenerator_1.PostmanGenerator();
+        this.markdown = new MarkdownGenerator_1.MarkdownGenerator();
+        this.html = new HtmlGenerator_1.HtmlGenerator();
+        this.openApi = new OpenApiGenerator_1.OpenApiGenerator();
+    }
+    generateAll(appName, outputDir) {
+        const routes = router_1.RouteRegistry.getInstance().getRoutes();
+        if (!fs_1.default.existsSync(outputDir)) {
+            fs_1.default.mkdirSync(outputDir, { recursive: true });
+        }
+        // Postman
+        const postmanJson = this.postman.generate(routes, appName);
+        fs_1.default.writeFileSync(path_1.default.join(outputDir, 'postman_collection.json'), JSON.stringify(postmanJson, null, 2));
+        // Environment
+        const envJson = {
+            name: `${appName} Env`,
+            values: [
+                { key: "base_url", value: "http://localhost:3000", enabled: true }
+            ]
+        };
+        fs_1.default.writeFileSync(path_1.default.join(outputDir, 'postman_environment.json'), JSON.stringify(envJson, null, 2));
+        // Markdown
+        const md = this.markdown.generate(routes, appName);
+        fs_1.default.writeFileSync(path_1.default.join(outputDir, 'DOCS.md'), md);
+        // HTML
+        const html = this.html.generate(routes, appName);
+        fs_1.default.writeFileSync(path_1.default.join(outputDir, 'api_docs.html'), html);
+        // OpenAPI
+        const openApiJson = this.openApi.generate(routes, appName);
+        fs_1.default.writeFileSync(path_1.default.join(outputDir, 'openapi.json'), JSON.stringify(openApiJson, null, 2));
+    }
+}
+exports.DocumentationGenerator = DocumentationGenerator;

package/dist/HtmlGenerator.d.ts

@@ -0,0 +1,6 @@
+import { RouteEntry } from '@arikajs/router';
+export declare class HtmlGenerator {
+    generate(routes: RouteEntry[], appName: string): string;
+    private renderGroup;
+    private groupByPrefix;
+}

package/dist/HtmlGenerator.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HtmlGenerator = void 0;
+class HtmlGenerator {
+    generate(routes, appName) {
+        const groups = this.groupByPrefix(routes);
+        const groupHtml = Object.entries(groups).map(([name, groupRoutes]) => this.renderGroup(name, groupRoutes)).join('');
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${appName} API Documentation</title>
+    <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;600;700&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --primary: #8b5cf6;
+            --bg: #f8fafc;
+            --card: #ffffff;
+            --text-main: #0f172a;
+            --text-muted: #64748b;
+            --border: #e2e8f0;
+            --get: #10b981;
+            --post: #3b82f6;
+            --put: #f59e0b;
+            --delete: #ef4444;
+        }
+
+        * { margin:0; padding:0; box-sizing:border-box; }
+        body { font-family: 'Plus Jakarta Sans', sans-serif; background: var(--bg); color: var(--text-main); line-height: 1.6; }
+        .container { max-width: 1000px; margin: 0 auto; padding: 4rem 2rem; }
+        header { margin-bottom: 4rem; }
+        h1 { font-size: 2.5rem; margin-bottom: 0.5rem; }
+        .badge { display: inline-block; padding: 0.25rem 0.75rem; background: var(--primary); color: white; border-radius: 99px; font-size: 0.8rem; font-weight: 600; }
+        
+        .group { margin-bottom: 3rem; }
+        .group-title { font-size: 1.5rem; margin-bottom: 1.5rem; border-bottom: 2px solid var(--border); padding-bottom: 0.5rem; text-transform: capitalize; }
+        
+        .route-card { background: var(--card); border: 1px solid var(--border); border-radius: 12px; padding: 1.5rem; margin-bottom: 1rem; transition: transform 0.2s; }
+        .route-card:hover { transform: translateY(-2px); box-shadow: 0 10px 20px rgba(0,0,0,0.05); }
+        
+        .route-header { display: flex; align-items: center; gap: 1rem; margin-bottom: 1rem; }
+        .method { padding: 0.25rem 0.75rem; border-radius: 6px; font-weight: 700; font-size: 0.8rem; min-width: 70px; text-align: center; color: white; }
+        .method.GET { background: var(--get); }
+        .method.POST { background: var(--post); }
+        .method.PUT { background: var(--put); }
+        .method.DELETE { background: var(--delete); }
+        .path { font-family: monospace; font-size: 1.1rem; font-weight: 600; color: var(--text-main); }
+        
+        .route-info { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; font-size: 0.9rem; }
+        .label { color: var(--text-muted); font-weight: 600; margin-bottom: 0.25rem; }
+        .value { color: var(--text-main); }
+        
+        .middleware-tag { display: inline-block; padding: 0.1rem 0.5rem; background: #f1f5f9; border: 1px solid var(--border); border-radius: 4px; font-size: 0.75rem; margin-right: 0.25rem; }
+        
+        footer { text-align: center; margin-top: 4rem; color: var(--text-muted); font-size: 0.8rem; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <header>
+            <div class="badge">ArikaJS Docs</div>
+            <h1>${appName}</h1>
+            <p>API documentation generated on ${new Date().toLocaleDateString()}</p>
+        </header>
+
+        ${groupHtml}
+
+        <footer>
+            Generated by @arikajs/docs &copy; 2026
+        </footer>
+    </div>
+</body>
+</html>`;
+    }
+    renderGroup(name, routes) {
+        const routesHtml = routes.map(route => `
+            <div class="route-card">
+                <div class="route-header">
+                    <span class="method ${route.method}">${route.method}</span>
+                    <span class="path">${route.path}</span>
+                </div>
+                <div class="route-info">
+                    <div>
+                        <div class="label">Route Name</div>
+                        <div class="value">${route.name || '-'}</div>
+                    </div>
+                    <div>
+                        <div class="label">Middleware</div>
+                        <div class="value">
+                            ${route.middleware.map(m => `<span class="middleware-tag">${typeof m === 'string' ? m : m.name || 'Closure'}</span>`).join('') || '-'}
+                        </div>
+                    </div>
+                </div>
+            </div>
+        `).join('');
+        return `
+            <div class="group">
+                <h2 class="group-title">${name.replace('/', '')}</h2>
+                ${routesHtml}
+            </div>
+        `;
+    }
+    groupByPrefix(routes) {
+        const groups = {};
+        routes.forEach(route => {
+            const group = route.prefix || 'General';
+            if (!groups[group])
+                groups[group] = [];
+            groups[group].push(route);
+        });
+        return groups;
+    }
+}
+exports.HtmlGenerator = HtmlGenerator;

package/dist/MarkdownGenerator.d.ts

@@ -0,0 +1,5 @@
+import { RouteEntry } from '@arikajs/router';
+export declare class MarkdownGenerator {
+    generate(routes: RouteEntry[], appName: string): string;
+    private groupByPrefix;
+}

package/dist/MarkdownGenerator.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownGenerator = void 0;
+class MarkdownGenerator {
+    generate(routes, appName) {
+        let markdown = `# API Documentation: ${appName}\n\n`;
+        markdown += `Generated on ${new Date().toLocaleDateString()}\n\n`;
+        const groups = this.groupByPrefix(routes);
+        for (const [group, groupRoutes] of Object.entries(groups)) {
+            markdown += `## ${group}\n\n`;
+            markdown += `| Method | Path | Name | Middleware |\n`;
+            markdown += `| :--- | :--- | :--- | :--- |\n`;
+            groupRoutes.forEach(route => {
+                const middleware = route.middleware.map(m => typeof m === 'string' ? m : m.name || 'Closure').join(', ') || '-';
+                markdown += `| **${route.method}** | \`${route.path}\` | ${route.name || '-'} | ${middleware} |\n`;
+            });
+            markdown += `\n`;
+        }
+        return markdown;
+    }
+    groupByPrefix(routes) {
+        const groups = {};
+        routes.forEach(route => {
+            const group = route.prefix || 'General';
+            if (!groups[group])
+                groups[group] = [];
+            groups[group].push(route);
+        });
+        return groups;
+    }
+}
+exports.MarkdownGenerator = MarkdownGenerator;

package/dist/OpenApiGenerator.d.ts

@@ -0,0 +1,6 @@
+import { RouteEntry } from '@arikajs/router';
+export declare class OpenApiGenerator {
+    generate(routes: RouteEntry[], appName: string): any;
+    private formatPaths;
+    private extractParameters;
+}

package/dist/OpenApiGenerator.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiGenerator = void 0;
+class OpenApiGenerator {
+    generate(routes, appName) {
+        return {
+            openapi: "3.0.0",
+            info: {
+                title: appName,
+                description: `API Specification for ${appName}`,
+                version: "1.0.0"
+            },
+            paths: this.formatPaths(routes),
+            components: {
+                schemas: {},
+                securitySchemes: {
+                    bearerAuth: {
+                        type: "http",
+                        scheme: "bearer",
+                        bearerFormat: "JWT"
+                    }
+                }
+            }
+        };
+    }
+    formatPaths(routes) {
+        const paths = {};
+        routes.forEach(route => {
+            const path = route.path.replace(/:([a-zA-Z0-9_]+)|\{([a-zA-Z0-9_]+)\}/g, '{$1$2}');
+            if (!paths[path]) {
+                paths[path] = {};
+            }
+            paths[path][route.method.toLowerCase()] = {
+                summary: route.name || `Endpoint for ${path}`,
+                tags: [route.prefix || 'General'],
+                parameters: this.extractParameters(route),
+                responses: {
+                    "200": {
+                        description: "Successful response",
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object"
+                                }
+                            }
+                        }
+                    }
+                }
+            };
+        });
+        return paths;
+    }
+    extractParameters(route) {
+        return route.paramKeys.map(key => ({
+            name: key,
+            in: "path",
+            required: true,
+            schema: {
+                type: "string"
+            }
+        }));
+    }
+}
+exports.OpenApiGenerator = OpenApiGenerator;

package/dist/PostmanGenerator.d.ts

@@ -0,0 +1,5 @@
+import { RouteEntry } from '@arikajs/router';
+export declare class PostmanGenerator {
+    generate(routes: RouteEntry[], appName: string): any;
+    private formatRoutes;
+}

package/dist/PostmanGenerator.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostmanGenerator = void 0;
+class PostmanGenerator {
+    generate(routes, appName) {
+        return {
+            info: {
+                name: appName,
+                _postman_id: Math.random().toString(36).substring(7),
+                description: `API Collection for ${appName}`,
+                schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+            },
+            item: this.formatRoutes(routes),
+            variable: [
+                {
+                    key: "base_url",
+                    value: "http://localhost:3000",
+                    type: "string"
+                }
+            ]
+        };
+    }
+    formatRoutes(routes) {
+        // Group routes by prefix/module
+        const groups = {};
+        routes.forEach(route => {
+            const groupName = route.prefix || 'General';
+            if (!groups[groupName]) {
+                groups[groupName] = [];
+            }
+            groups[groupName].push({
+                name: route.name || route.path,
+                request: {
+                    method: route.method,
+                    header: [
+                        {
+                            key: "Content-Type",
+                            value: "application/json"
+                        },
+                        {
+                            key: "Accept",
+                            value: "application/json"
+                        }
+                    ],
+                    url: {
+                        raw: "{{base_url}}" + route.path,
+                        host: ["{{base_url}}"],
+                        path: route.path.split('/').filter(p => p !== '')
+                    }
+                },
+                response: []
+            });
+        });
+        return Object.keys(groups).map(name => ({
+            name: name.charAt(0).toUpperCase() + name.slice(1).replace('/', ''),
+            item: groups[name]
+        }));
+    }
+}
+exports.PostmanGenerator = PostmanGenerator;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { DocumentationGenerator } from './Generator';
+export { PostmanGenerator } from './PostmanGenerator';
+export { MarkdownGenerator } from './MarkdownGenerator';
+export { HtmlGenerator } from './HtmlGenerator';
+export { OpenApiGenerator } from './OpenApiGenerator';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiGenerator = exports.HtmlGenerator = exports.MarkdownGenerator = exports.PostmanGenerator = exports.DocumentationGenerator = void 0;
+var Generator_1 = require("./Generator");
+Object.defineProperty(exports, "DocumentationGenerator", { enumerable: true, get: function () { return Generator_1.DocumentationGenerator; } });
+var PostmanGenerator_1 = require("./PostmanGenerator");
+Object.defineProperty(exports, "PostmanGenerator", { enumerable: true, get: function () { return PostmanGenerator_1.PostmanGenerator; } });
+var MarkdownGenerator_1 = require("./MarkdownGenerator");
+Object.defineProperty(exports, "MarkdownGenerator", { enumerable: true, get: function () { return MarkdownGenerator_1.MarkdownGenerator; } });
+var HtmlGenerator_1 = require("./HtmlGenerator");
+Object.defineProperty(exports, "HtmlGenerator", { enumerable: true, get: function () { return HtmlGenerator_1.HtmlGenerator; } });
+var OpenApiGenerator_1 = require("./OpenApiGenerator");
+Object.defineProperty(exports, "OpenApiGenerator", { enumerable: true, get: function () { return OpenApiGenerator_1.OpenApiGenerator; } });

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@arikajs/docs",
+  "version": "0.2.0",
+  "description": "API documentation and Postman collection generator for ArikaJS.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "npm run build && node --test 'dist/tests/**/*.test.js'"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "arika",
+    "arika-js",
+    "docs",
+    "postman",
+    "openapi",
+    "documentation"
+  ],
+  "dependencies": {
+    "@arikajs/router": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  },
+  "author": "Prakash Tank"
+}