🔍 API Scout

The ultimate API documentation generator that scouts your codebase and creates beautiful, interactive documentation automatically.

API Scout intelligently analyzes your code across multiple frameworks and generates comprehensive documentation with interactive testing capabilities, security analysis, and multi-language code examples.

✨ Features

🚀 Automatic API Discovery

• Multi-framework support: Express.js, NestJS, FastAPI, Spring Boot
• Intelligent parsing: AST-based analysis for accurate endpoint detection
• TypeScript support: Full decorator and type annotation parsing
• Smart detection: Automatically identifies frameworks and patterns

🧪 Interactive API Testing

• Built-in API tester with request builder interface
• Authentication support: Bearer tokens, API keys, Basic auth, OAuth
• Environment management: Switch between dev/staging/production
• Request history: Save and replay API calls
• Real-time responses with syntax highlighting

📋 Rich Documentation

• Multiple output formats: Swagger UI, ReDoc, Custom interactive
• Code examples: Auto-generated cURL, JavaScript, and Python examples
• Parameter detection: Automatic extraction of path, query, and body parameters
• Middleware documentation: Security guards, interceptors, and middleware chains

🔐 Security Analysis

• Authentication scheme detection: JWT, OAuth, Sessions, Passport
• Security recommendations: Best practices and vulnerability warnings
• Environment analysis: Scans .env files for security configurations
• Compliance reporting: Security posture assessment with actionable insights

🎨 Beautiful UI

• Modern design: Responsive interface with gradient themes
• Real-time search: Filter endpoints instantly
• Method filtering: Browse by HTTP methods (GET, POST, PUT, DELETE)
• Syntax highlighting: Code examples with proper formatting

🚀 Quick Start

Installation

# Install globally
npm install -g api-scout

# Or use with npx (no installation required)
npx api-scout --help

Basic Usage

# Scout your current project
api-scout generate

# Scout with specific options
api-scout generate --input ./src --output ./docs --framework express

# Serve documentation locally
api-scout serve

# Watch mode for development
api-scout watch

Your first API documentation in 30 seconds:

# 1. Navigate to your API project
cd my-api-project

# 2. Generate documentation
npx api-scout generate

# 3. Serve and view
npx api-scout serve
# Open http://localhost:3000

📋 Commands

generate (alias: gen)

Scout and generate API documentation from your codebase.

api-scout generate [options]

Options:
  -i, --input <path>        Input directory to scan (default: current directory)
  -o, --output <path>       Output directory for docs (default: ./docs-output)
  -f, --framework <type>    Target framework: express, nestjs, fastapi, spring, all (default: all)
  -t, --template <name>     Documentation template: swagger, redoc, custom (default: swagger)
  --config <path>           Configuration file path
  --exclude <patterns>      Exclude patterns (comma-separated)
  --include-private         Include private/internal APIs

Examples:

# Generate docs for Express.js project
api-scout generate --framework express --template custom

# Scan specific directory with exclusions
api-scout generate --input ./api --exclude "test/**,*.spec.js"

# Generate with custom configuration
api-scout generate --config ./scout.config.js

serve

Serve generated documentation with a local web server.

api-scout serve [options]

Options:
  -p, --port <number>       Port to serve on (default: 3000)
  -d, --docs <path>         Documentation directory (default: ./docs-output)

Examples:

# Serve on default port
api-scout serve

# Serve on custom port
api-scout serve --port 8080

watch

Watch your codebase and automatically regenerate documentation on changes.

api-scout watch [options]

Options:
  -i, --input <path>        Input directory to watch (default: current directory)
  -o, --output <path>       Output directory for docs (default: ./docs-output)
  --debounce <ms>           Debounce time in milliseconds (default: 1000)

🛠 Framework Support

JavaScript/TypeScript

• Express.js: Routes, middleware, parameter extraction
• NestJS: Controllers, decorators, guards, interceptors, DTOs
• Next.js: API routes in pages/api and App Router (coming soon)
• Koa: Middleware and routing patterns (coming soon)
• Fastify: Route definitions and schemas (coming soon)

Python

• FastAPI: Decorators, Pydantic models, dependencies
• Flask: Route decorators and blueprints (coming soon)
• Django: Views, serializers, URL patterns (coming soon)

Java

• Spring Boot: Controllers, annotations, entities, repositories

Supported Patterns

Express.js Example:

// Automatically detected and documented
app.get('/api/users/:id', authenticate, (req, res) => {
  // GET /api/users/:id with authentication middleware
});

NestJS Example:

@Controller('api/users')
export class UsersController {
  @Get(':id')
  @UseGuards(AuthGuard('jwt'))
  async findOne(@Param('id') id: string): Promise<User> {
    // Automatically extracts: route, guards, parameters, return type
  }
}

FastAPI Example:

@app.get("/users/{user_id}")
async def get_user(user_id: int, db: Session = Depends(get_db)):
    """Automatically extracts: route, parameters, dependencies, docstring"""
    return user

⚙️ Configuration

Create a scout.config.js file in your project root:

module.exports = {
  // Input/Output
  input: './src',
  output: './api-docs',
  
  // Framework targeting
  framework: 'express', // 'express', 'nestjs', 'fastapi', 'spring', 'all'
  
  // Documentation template
  template: 'custom', // 'swagger', 'redoc', 'custom'
  
  // File exclusions
  exclude: [
    'node_modules/**',
    '**/*.test.*',
    'dist/**'
  ],
  
  // Server configuration
  server: {
    port: 3000,
    host: 'localhost'
  },
  
  // Watch mode settings
  watch: {
    debounce: 1000
  },
  
  // Documentation customization
  customization: {
    title: 'My API Documentation',
    description: 'Comprehensive API documentation for my application',
    version: '1.0.0',
    contact: {
      name: 'API Support Team',
      email: '[email protected]'
    },
    servers: [
      {
        url: 'https://api.mycompany.com/v1',
        description: 'Production server'
      },
      {
        url: 'http://localhost:3000',
        description: 'Development server'
      }
    ]
  },
  
  // Security analysis
  security: {
    enableAnalysis: true,
    reportLevel: 'detailed' // 'basic', 'detailed'
  },
  
  // Advanced options
  advanced: {
    maxFileSize: 1024 * 1024, // 1MB
    maxConcurrentFiles: 10,
    enableCache: true,
    logLevel: 'info' // 'debug', 'info', 'warn', 'error'
  }
};

📊 Output Formats

1. Swagger UI (--template swagger)

• Industry-standard OpenAPI documentation
• Try-it-out functionality
• Schema validation
• Export to various formats

2. ReDoc (--template redoc)

• Clean, responsive documentation
• Advanced schema visualization
• Better navigation for large APIs
• Mobile-friendly design

3. Custom Interactive (--template custom)

• Modern, custom-designed interface
• Advanced interactive testing
• Real-time search and filtering
• Security analysis dashboard
• Multi-language code examples

🔐 Security Features

API Scout includes comprehensive security analysis:

Authentication Detection

• JWT: Token-based authentication patterns
• OAuth: OAuth 2.0 flow detection
• API Keys: Header and query-based API keys
• Basic Auth: Username/password authentication
• Sessions: Cookie-based session management
• Passport: Passport.js strategy detection

Security Analysis

• Middleware detection: Authentication guards and interceptors
• Environment scanning: Security-related environment variables
• Vulnerability warnings: Common security issues
• Best practice recommendations: Security improvement suggestions

Sample Security Report

{
  "schemes": [
    {
      "type": "JWT",
      "library": "jsonwebtoken",
      "files": ["auth.js", "middleware.js"]
    }
  ],
  "recommendations": [
    {
      "priority": "high",
      "title": "JWT Token Expiration",
      "description": "JWT tokens should have expiration times configured"
    }
  ]
}

🧪 Interactive Testing

The built-in API tester provides:

Request Builder

• Form-based request construction
• Parameter auto-completion
• Body editor with JSON validation
• Header management

Authentication Management

• Bearer token storage
• API key configuration
• Basic auth credentials
• Environment-specific settings

Response Analysis

• Syntax-highlighted JSON/XML
• Response time measurement
• Status code interpretation
• Header inspection

Request History

• Persistent request storage
• Quick replay functionality
• Export/import capabilities
• Search and filtering

📁 Project Structure

my-api-project/
├── src/
│   ├── routes/
│   │   ├── users.js       # Express routes
│   │   └── products.js
│   ├── controllers/
│   │   └── auth.controller.ts  # NestJS controllers
│   └── models/
│       └── User.java      # Spring entities
├── scout.config.js        # API Scout configuration
└── docs-output/           # Generated documentation
    ├── index.html         # Documentation website
    ├── openapi.json       # OpenAPI specification
    ├── api-data.json      # Extracted API data
    └── report.json        # Analysis report

🚀 Publishing & Deployment

Static Hosting

Deploy your generated documentation to any static hosting service:

# Generate documentation
api-scout generate --output ./public/docs

# Deploy to Netlify, Vercel, GitHub Pages, etc.
# The docs-output directory contains a complete static website

CI/CD Integration

GitHub Actions Example:

name: Generate API Documentation
on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install API Scout
        run: npm install -g api-scout
      
      - name: Generate Documentation
        run: api-scout generate --output ./docs
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Docker Integration

FROM node:18-alpine
RUN npm install -g api-scout
COPY . /app
WORKDIR /app
RUN api-scout generate
EXPOSE 3000
CMD ["api-scout", "serve"]

🤖 API & Programmatic Usage

Use API Scout programmatically in your applications:

const APIScout = require('api-scout');

const scout = new APIScout({
  input: './src',
  output: './docs',
  framework: 'express',
  template: 'custom'
});

// Generate documentation
const result = await scout.generate();
console.log(`Generated docs for ${result.endpoints.length} endpoints`);

// Start watch mode
const watcher = await scout.watch();

// Serve documentation
await scout.serve({ port: 3000 });

🔧 Advanced Usage

Custom Templates

Create your own documentation templates:

// scout.config.js
module.exports = {
  template: 'custom',
  templatePath: './my-custom-template',
  customization: {
    theme: {
      primaryColor: '#1976d2',
      accentColor: '#ff4081'
    }
  }
};

Plugin System (coming soon)

// scout.config.js
module.exports = {
  plugins: [
    'api-scout-plugin-postman',
    'api-scout-plugin-insomnia',
    './my-custom-plugin.js'
  ]
};

Multiple Framework Projects

# Scan different parts of a monorepo
api-scout generate --input ./services/api --framework express
api-scout generate --input ./services/auth --framework nestjs
api-scout generate --input ./services/data --framework fastapi

📈 Performance & Optimization

Large Codebases

• Parallel processing: Concurrent file analysis
• Smart caching: Incremental parsing for faster rebuilds
• Memory optimization: Streaming analysis for large files
• Selective scanning: Framework-specific targeting

Performance Tips

// scout.config.js
module.exports = {
  // Limit file size to improve performance
  advanced: {
    maxFileSize: 500 * 1024, // 500KB
    maxConcurrentFiles: 20,
    enableCache: true
  },
  
  // Exclude unnecessary files
  exclude: [
    'node_modules/**',
    '**/*.min.js',
    'coverage/**',
    'dist/**'
  ]
};

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/your-username/api-scout.git
cd api-scout

# Install dependencies
npm install

# Run in development mode
npm run dev

# Test with example projects
npm run test:examples

Adding Framework Support

1. Create a new parser in src/parsers/
2. Add detection logic in src/utils/framework-detector.js
3. Register the parser in src/scanner/index.js
4. Add tests and examples

Contributing Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation
• Submit detailed pull requests

📄 License

MIT License - see LICENSE file for details.

🆘 Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Documentation
• Examples: Example Projects

🏆 Comparison

| Feature | API Scout | Swagger Codegen | Insomnia | Postman | |---------|-----------|-----------------|----------|---------| | Auto-discovery | ✅ | ❌ | ❌ | ❌ | | Multi-framework | ✅ | ⚠️ Limited | ❌ | ❌ | | Interactive testing | ✅ | ❌ | ✅ | ✅ | | Security analysis | ✅ | ❌ | ❌ | ⚠️ Basic | | Code examples | ✅ | ✅ | ⚠️ Limited | ✅ | | Free & open source | ✅ | ✅ | ⚠️ Freemium | ⚠️ Freemium | | CLI integration | ✅ | ✅ | ❌ | ❌ |

🎯 Roadmap

• [ ] Plugin System: Extensible architecture for custom parsers
• [ ] More Frameworks: Django, Flask, Ruby on Rails, ASP.NET Core
• [ ] Export Formats: PDF, Markdown, Postman collections
• [ ] Performance Metrics: API performance analysis and recommendations
• [ ] Team Features: Collaboration tools and shared workspaces
• [ ] Cloud Integration: Deploy documentation to cloud platforms
• [ ] API Monitoring: Health checks and uptime monitoring

Made with ❤️ by the API Scout team

Star ⭐ this project if it helped you build better API documentation!