api-scout/README.md

🔍 Automatically scout, discover and generate beautiful interactive API documentation from your codebase. Supports Express.js, NestJS, FastAPI, Spring Boot with interactive testing and security analysis.

# 🔍 API Scout

[![npm version](https://badge.fury.io/js/api-scout.svg)](https://badge.fury.io/js/api-scout)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)

**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.

![API Scout Demo](https://via.placeholder.com/800x400/667eea/ffffff?text=API+Scout+Demo)

## ✨ 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

```bash
# Install globally
npm install -g api-scout

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

### Basic Usage

```bash
# 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:

```bash
# 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.

```bash
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:**
```bash
# 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.

```bash
api-scout serve [options]

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

**Examples:**
```bash
# 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.

```bash
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:**
```javascript
// Automatically detected and documented
app.get('/api/users/:id', authenticate, (req, res) => {
  // GET /api/users/:id with authentication middleware
});
```

**NestJS Example:**
```typescript
@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:**
```python
@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:

```javascript
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: 'api-support@mycompany.com'
    },
    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**
```json
{
  "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:

```bash
# 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:**
```yaml
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**
```dockerfile
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:

```javascript
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:

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

### **Plugin System** *(coming soon)*
```javascript
// scout.config.js
module.exports = {
  plugins: [
    'api-scout-plugin-postman',
    'api-scout-plugin-insomnia',
    './my-custom-plugin.js'
  ]
};
```

### **Multiple Framework Projects**
```bash
# 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**
```javascript
// 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**
```bash
# 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](LICENSE) file for details.

## 🆘 Support & Community

- **Issues**: [GitHub Issues](https://github.com/your-username/api-scout/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/api-scout/discussions)
- **Documentation**: [Full Documentation](https://github.com/your-username/api-scout/wiki)
- **Examples**: [Example Projects](./examples/)

## 🏆 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!**