Auto Doc Gen

Automatically generates API documentation, Postman collections, OpenAPI specs, and test files from your backend codebase.

What It Does

• Scans TypeScript files for route definitions
• Generates Postman collections with organized routes
• Creates OpenAPI 3.0 specifications and Swagger UI
• Generates automated test files
• Tests endpoints and captures real responses
• Detects authentication endpoints and manages tokens

Installation

npm install -g @devxcant/auto-doc-gen

Or install locally:

npm install @devxcant/auto-doc-gen
bun install @devxcant/auto-doc-gen

Commands

Basic Usage

Test non-auth endpoints and generate all files:

auto-doc-gen /path/to/backend

Or using the --path option:

auto-doc-gen --path /path/to/backend

What it does:

• Scans routes
• Tests non-auth endpoints only (requires backend to be running)
• Generates all files: Postman collection, OpenAPI spec, Swagger UI, test files, documentation, and test report

With Authentication

Test all endpoints including auth (prompts for credentials):

auto-doc-gen /path/to/backend --all

Or using the --path option:

auto-doc-gen --path /path/to/backend --all

What it does:

• Scans routes
• Prompts for email and password
• Tests all endpoints including auth endpoints
• Generates all files: Postman collection, OpenAPI spec, Swagger UI, test files, documentation, and test report

With Remote Backend

Test against a remote server:

auto-doc-gen /path/to/backend --all --url https://api.example.com

What it does: Tests endpoints at the specified URL instead of localhost. With --all, prompts for email and password.

Custom Output Directory

Generate files to a specific location:

auto-doc-gen /path/to/backend --all -o ~/Documents/api-docs

What it does: Creates auto-doc-gen/ folder in the specified output directory.

Using npx/bunx (Local Installation)

If installed locally, prefix commands:

npx @devxcant/auto-doc-gen /path/to/backend --all
bunx @devxcant/auto-doc-gen /path/to/backend --all

Options

Core Options

--path, -p <path>      Path to backend folder (default: ".")
--all                  Test auth endpoints (prompts for credentials)
--url <url>            Base URL for testing (default: http://localhost:5050)
--output, -o <path>    Output directory (default: current directory)
--verbose              Show detailed output and debugging information
--help, -h             Show help
--version, -V          Show version

New Features (v2.0.0)

--mock-server          Generate Express.js mock server
--dashboard            Generate API health dashboard
--contract-tests       Generate contract test files
--security-scan        Run security analysis
--performance          Generate performance report
--code-examples        Generate code examples (cURL, JS, Python, Go)
--load-test            Generate load testing scripts (k6, Artillery)
--export-formats       Export to Insomnia and Thunder Client
--diagrams             Generate API flow diagrams
--ci-cd                Generate CI/CD configuration files
--versioning           Detect and report API versioning
--rate-limits          Detect and document rate limits

Note: Use --all to test auth endpoints (prompts for credentials). Without --all, only non-auth endpoints are tested.

New Features in v2.0.0

🚀 Mock Server Generation

Generate a working Express.js mock server from your API with real response data:

auto-doc-gen ./backend --mock-server

Creates a ready-to-run mock server in auto-doc-gen/mock-server/.

📊 API Health Dashboard

Beautiful HTML dashboard with visual metrics and endpoint status:

auto-doc-gen ./backend --dashboard

🧪 Contract Testing

Generate contract test files to validate API responses:

auto-doc-gen ./backend --contract-tests

🔒 Security Scanning

Automated security analysis with recommendations:

auto-doc-gen ./backend --security-scan

⚡ Performance Analysis

Measure and analyze endpoint response times:

auto-doc-gen ./backend --performance

💻 Code Examples

Generate code examples in multiple languages:

auto-doc-gen ./backend --code-examples

📈 Load Testing

Generate k6 and Artillery load test scripts:

auto-doc-gen ./backend --load-test

📦 Additional Export Formats

Export to Insomnia and Thunder Client:

auto-doc-gen ./backend --export-formats

📐 API Diagrams

Generate visual flow diagrams:

auto-doc-gen ./backend --diagrams

🔄 CI/CD Integration

Generate GitHub Actions and GitLab CI configs:

auto-doc-gen ./backend --ci-cd

🔢 Versioning Detection

Detect and report API versioning patterns:

auto-doc-gen ./backend --versioning

⏱️ Rate Limit Detection

Detect and document rate limits:

auto-doc-gen ./backend --rate-limits

Combine Multiple Features

# Full suite
auto-doc-gen ./backend --all --mock-server --dashboard --security-scan --performance

# Development workflow
auto-doc-gen ./backend --mock-server --code-examples --diagrams

# Production readiness
auto-doc-gen ./backend --all --security-scan --performance --load-test

Generated Files

All files are generated in the auto-doc-gen/ folder:

Core Files (Always Generated)

• postman_collection.json - Import into Postman
• local_environment.postman_environment.json - Local environment variables
• production_environment.postman_environment.json - Production environment variables
• openapi.json - OpenAPI 3.0 specification
• api-docs.html - Interactive Swagger UI
• API_DOCUMENTATION.md - Markdown documentation
• tests/auto/*.test.ts - Automated test files
• report.json - Live test results

Feature-Specific Files (Generated with flags)

With --mock-server:

• mock-server/server.js - Express.js mock server
• mock-server/package.json - Dependencies
• mock-server/README.md - Usage instructions

With --dashboard:

• dashboard.html - API health dashboard

With --contract-tests:

• tests/contract/contract.test.ts - Contract test files

With --security-scan:

• security-scan.json - Security analysis report
• security-scan.html - Visual security report

With --performance:

• performance.json - Performance metrics
• performance.html - Performance dashboard

With --code-examples:

• code-examples/curl.sh - cURL examples
• code-examples/javascript.js - JavaScript examples
• code-examples/python.py - Python examples
• code-examples/go.go - Go examples

With --load-test:

• load-test/k6-script.js - k6 load test script
• load-test/artillery.yml - Artillery config

With --export-formats:

• insomnia_collection.json - Insomnia format
• thunder-client/collection.json - Thunder Client format

With --diagrams:

• diagrams.html - Interactive diagrams
• diagrams.mmd - Mermaid source

With --ci-cd:

• ci-cd/.github/workflows/api-tests.yml - GitHub Actions
• ci-cd/.gitlab-ci.yml - GitLab CI

With --versioning:

• versioning.json - Versioning report
• versioning.html - Visual versioning report

With --rate-limits:

• rate-limits.json - Rate limit data
• rate-limits.html - Rate limit report

Requirements

• Node.js 18.0.0 or higher
• TypeScript route files using router.get(), router.post(), etc.
• Backend must be running (for live endpoint testing)

Examples

Test non-auth endpoints and generate all files:

auto-doc-gen ./backend

Test all endpoints including auth (prompts for credentials):

auto-doc-gen ./backend --all

Test remote API:

auto-doc-gen ./backend --url https://staging-api.example.com

Generate to specific folder:

auto-doc-gen ./backend --all -o ~/Desktop/api-docs

Changelog

See CHANGELOG.md for detailed version history and new features.

Version 2.0.0 Highlights

This major release adds 12 new powerful features:

1. Mock Server - Generate working mock servers
2. Health Dashboard - Visual API monitoring
3. Contract Tests - API validation tests
4. Security Scan - Automated security analysis
5. Performance Reports - Response time analysis
6. Code Examples - Multi-language code snippets
7. Load Testing - k6 and Artillery scripts
8. Export Formats - Insomnia & Thunder Client
9. API Diagrams - Visual flow charts
10. CI/CD Configs - GitHub Actions & GitLab CI
11. Versioning Detection - API version analysis
12. Rate Limits - Rate limit documentation

All features are opt-in via flags. Your existing workflows remain unchanged!