swagger-auto-generate/README.md

Automatically generate Swagger JSDoc documentation for Express applications

# Swagger Auto Generate

🚀 **Zero-config Swagger documentation for Express apps with auto-generation on save**

Automatically generate and serve Swagger documentation for your Express APIs with real-time updates.

## Quick Start

### 1. Install

```bash
npm install swagger-auto-generate swagger-jsdoc swagger-ui-express
```

### 2. Add to your Express app

```javascript
import express from 'express';
import { ExpressIntegration } from 'swagger-auto-generate';

const app = express();
const PORT = process.env.PORT || 3000;

// Your routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.post('/api/users', (req, res) => {
  res.status(201).json({ message: 'User created' });
});

// Setup Swagger (auto-generates on file changes)
const swaggerIntegration = new ExpressIntegration({
  app,
  swaggerConfig: {
    inputFolders: ['routes', 'controllers'],
    swaggerInfo: {
      title: 'My API',
      version: '1.0.0',
      description: 'Auto-generated docs',
    },
    watchMode: true, // Auto-regenerate on save
    swaggerUi: {
      enabled: true,
      route: '/api-docs',
    },
  },
});

// Start server
app.listen(PORT, async () => {
  await swaggerIntegration.setup();
  console.log(`🚀 Server: http://localhost:${PORT}`);
  console.log(`📚 Swagger: http://localhost:${PORT}/api-docs`);
});
```

## Features

- ✅ **Auto-generation on save** - Documentation updates automatically
- ✅ **Zero configuration** - Works out of the box
- ✅ **Express integration** - One-line setup
- ✅ **Swagger UI** - Beautiful documentation interface
- ✅ **Multiple formats** - JSON, YAML endpoints

## API Reference

### ExpressIntegration

```javascript
const integration = new ExpressIntegration({
  app, // Express app instance
  swaggerConfig, // Configuration object
  autoSetup: true, // Auto-start file watching
});

await integration.setup(); // Setup Swagger UI
await integration.regenerate(); // Manual regeneration
await integration.generateJSDocComments(); // Add JSDoc to files
```

### Configuration

```javascript
const swaggerConfig = {
  inputFolders: ['routes', 'controllers'], // Folders to scan
  outputFile: 'swagger-output.json', // Output file
  swaggerInfo: {
    title: 'My API',
    version: '1.0.0',
    description: 'Auto-generated docs',
    host: 'localhost:3000',
    basePath: '/api',
    schemes: ['http'],
  },
  watchMode: true, // Auto-regenerate on save
  verbose: false,
  swaggerUi: {
    enabled: true,
    route: '/api-docs',
    options: {
      explorer: true,
      customSiteTitle: 'My API Documentation',
    },
  },
};
```

## Route Examples

### Basic Route

```javascript
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});
```

### Route with Parameters

```javascript
app.get('/api/users/:id', (req, res) => {
  const { id } = req.params;
  res.json({ user: { id } });
});
```

### POST Route

```javascript
app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  res.status(201).json({ message: 'User created' });
});
```

## Generated Documentation

Your routes automatically generate:

- 📄 **Swagger UI** - Interactive documentation at `/api-docs`
- 📄 **JSON endpoint** - `/api-docs/json`
- 📄 **YAML endpoint** - `/api-docs/yaml`

## Auto-Generation

When `watchMode: true` is enabled:

- 🔄 **File changes** trigger regeneration
- 🔄 **New routes** are automatically detected
- 🔄 **Swagger UI** updates in real-time
- 🔄 **Debounced updates** (1 second delay)

## License

MIT License - see LICENSE file for details.

---


**Made with ❤️ for Express developers**