apx-toolkit/docs/archive/MOCK-SERVER-GENERATOR.md

Automatically discover APIs and generate complete integration packages: code in 12 languages, TypeScript types, test suites, SDK packages, API documentation, mock servers, performance reports, and contract tests. Saves 2-4 weeks of work in seconds.

# 🔄 API Mock Server Generator - Detailed Spec

**The #1 most needed feature that doesn't exist yet**

---

## 🎯 The Problem

Developers waste hours creating mock servers manually:
- Write mock server code
- Create fake data
- Handle edge cases
- Test mock responses
- Keep mocks in sync with real APIs

**Time:** 4-8 hours per API  
**Pain:** High - blocks development when APIs are down

---

## ✨ The Solution

**APX automatically generates production-ready mock servers from discovered APIs**

### What It Generates:

1. **Mock Server Code**
   - Express.js / Fastify server
   - All endpoints mocked
   - Real response data used
   - Error scenarios included

2. **Mock Data**
   - Extracted from real API responses
   - Multiple examples per endpoint
   - Edge cases included
   - Realistic data patterns

3. **Error Handling**
   - 400, 401, 403, 404, 500 errors
   - Rate limit simulation
   - Timeout scenarios
   - Network errors

4. **Configuration**
   - Environment variables
   - Port configuration
   - CORS setup
   - Logging

5. **Testing**
   - Test scripts
   - Validation
   - Health checks

---

## 📦 Output Structure

```
mock-server/
├── server.js              # Main mock server
├── routes/
│   ├── posts.js          # Mock endpoints
│   └── users.js
├── data/
│   ├── posts.json       # Real API data
│   └── users.json
├── errors/
│   └── scenarios.json    # Error cases
├── package.json
├── README.md
└── test/
    └── mock-server.test.js
```

---

## 💻 Generated Code Example

### Mock Server (Express.js)
```javascript
// Auto-generated by APX
const express = require('express');
const app = express();

// Mock data from real API
const posts = require('./data/posts.json');

app.get('/posts', (req, res) => {
  // Simulate real API behavior
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;
  
  const start = (page - 1) * limit;
  const end = start + limit;
  const paginated = posts.slice(start, end);
  
  res.json({
    data: paginated,
    page,
    limit,
    total: posts.length
  });
});

app.get('/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  if (!post) {
    return res.status(404).json({ error: 'Post not found' });
  }
  res.json(post);
});

// Error scenarios
app.get('/posts/error', (req, res) => {
  res.status(500).json({ error: 'Internal server error' });
});

app.listen(3000, () => {
  console.log('Mock server running on http://localhost:3000');
});
```

### Mock Data (from real API)
```json
// data/posts.json - Real data from API
[
  {
    "id": 1,
    "title": "Real title from API",
    "body": "Real body content",
    "userId": 1
  }
]
```

---

## 🎯 Features

### 1. Real Data Usage
- Uses actual API responses
- No fake data generation
- Realistic scenarios

### 2. Error Simulation
- Configurable error rates
- Specific error scenarios
- Rate limit simulation

### 3. Pagination Support
- Handles pagination correctly
- Configurable page sizes
- Real pagination logic

### 4. Authentication Mocking
- OAuth token simulation
- API key handling
- Bearer token support

### 5. WebSocket Mocking
- WebSocket server
- Message simulation
- Connection handling

---

## 🚀 Usage

### Generated Commands:
```bash
# Start mock server
npm run mock:start

# Run tests
npm run mock:test

# Generate new mocks
apx generate-mocks --api-url=https://api.example.com
```

---

## 💰 Value Proposition

### Time Saved:
- **Manual:** 4-8 hours per API
- **With APX:** 2 minutes
- **Savings:** 120-240x faster

### Benefits:
- ✅ Test without real API
- ✅ Offline development
- ✅ Predictable test data
- ✅ Faster CI/CD
- ✅ No API dependencies

---

## 🎯 Implementation Plan

### Phase 1: Basic Mock Server (Week 1)
- Express.js server generation
- Basic endpoint mocking
- Real data extraction
- Simple error handling

### Phase 2: Advanced Features (Week 2)
- Error scenarios
- Rate limiting
- Authentication
- WebSocket support

### Phase 3: Testing & Polish (Week 3)
- Test generation
- Documentation
- CLI commands
- Integration

---

## 🏆 Why This Is #1 Priority

1. **Huge Pain Point** - Every developer needs mocks
2. **Time Saver** - Saves hours per API
3. **Unique** - No tool does this automatically
4. **High Value** - Enables offline development
5. **Easy to Demo** - Clear before/after

---

**This feature alone would make APX indispensable!** 🚀