# API Documentation Access Guide

This guide explains how to access and use the comprehensive API documentation for the Corrad AF 2024 API Platform.

## 🌐 Live API Documentation

### Scalar API Reference (Interactive Documentation)
**URL:** `http://localhost:3000/api-docs`

- **Interactive Interface**: Modern, user-friendly API explorer
- **Try It Out**: Test API endpoints directly from the documentation
- **Multiple Themes**: Choose from 10+ beautiful themes
- **Real-time Testing**: Send requests and see responses immediately
- **Authentication**: Built-in support for Bearer token authentication

### OpenAPI Specification (Swagger JSON)
**URL:** `http://localhost:3000/api/openapi`

- **Dynamic Server URLs**: Automatically detects your current host
- **Complete Specification**: All 79+ endpoints documented
- **Import Ready**: Use with Postman, Insomnia, or other API tools
- **Cache Optimized**: 5-minute cache for better performance

### Static OpenAPI File
**URL:** `http://localhost:3000/openapi.json`

- **Static Version**: Original OpenAPI specification file
- **Backup Access**: Alternative if dynamic endpoint is unavailable

## 📱 Access Methods

### 1. Browser Access
Open any web browser and navigate to:
```
http://localhost:3000/api-docs
```

### 2. Postman Import
1. Open Postman
2. Click "Import" → "Link"
3. Enter: `http://localhost:3000/api/openapi`
4. Click "Continue" → "Import"

### 3. Insomnia Import
1. Open Insomnia
2. Click "Create" → "Import From" → "URL"
3. Enter: `http://localhost:3000/api/openapi`
4. Click "Fetch and Import"

### 4. Swagger UI
Use any Swagger UI instance with the URL:
```
http://localhost:3000/api/openapi
```

### 5. curl Access
Fetch the OpenAPI specification:
```bash
curl http://localhost:3000/api/openapi
```

## 🔧 Features

### Interactive Documentation
- **Modern UI**: Clean, responsive design
- **Code Examples**: Request/response examples for all endpoints
- **Authentication**: Integrated login and token management
- **Real-time Testing**: Send actual requests to the API
- **Multiple Formats**: JSON, form-data, and URL-encoded support

### API Categories
1. **Authentication** (3 endpoints)
   - Login, logout, token validation
2. **Business Logic** (1 endpoint)
   - Asnaf profile analysis with AI
3. **API Platform** (3 endpoints)
   - HTTP proxy, OAuth2 flows
4. **Metabase Integration** (1 endpoint)
   - Analytics token management
5. **Development Tools** (70+ endpoints)
   - User, role, menu management
   - Database operations
   - Content management
   - Configuration tools

### Authentication
Most endpoints require a Bearer token. To authenticate:

1. Use the `/api/auth/login` endpoint
2. Copy the returned token
3. Add to Authorization header: `Bearer <your-token>`

## 🎨 Customization

### Theme Options
Access the settings panel in the documentation to choose from:
- Default
- Alternate
- Moon (Dark)
- Purple
- Solarized
- Blue Planet
- Saturn
- Kepler
- Mars
- Deep Space

### Layout Options
- **Modern**: Three-column layout with sidebar
- **Classic**: Two-column traditional layout

## 🚀 Quick Start

1. **Start the Server**
   ```bash
   npm run dev
   # or
   yarn dev
   ```

2. **Access Documentation**
   Open: `http://localhost:3000/api-docs`

3. **Authenticate**
   - Use the login endpoint
   - Enter your credentials
   - Token will be automatically saved

4. **Explore APIs**
   - Browse by category
   - Try the "Send Request" button
   - View real responses

## 🔗 URLs Summary

| Service | URL | Description |
|---------|-----|-------------|
| **Interactive Docs** | `http://localhost:3000/api-docs` | Main API documentation interface |
| **OpenAPI Spec** | `http://localhost:3000/api/openapi` | Dynamic OpenAPI JSON |
| **Static Spec** | `http://localhost:3000/openapi.json` | Static OpenAPI file |
| **Postman Collection** | `./postman_collection.json` | Ready-to-import Postman collection |
| **Preview Mode** | `http://localhost:3000/api-docs?preview=true` | Preview with custom settings |

## 📋 Postman Collection

A complete Postman collection is available in the root directory:
- **File**: `postman_collection.json`
- **Endpoints**: All 79+ API endpoints
- **Environment**: Pre-configured variables
- **Authentication**: Automatic token management
- **Examples**: Sample requests and responses

## 🔧 Troubleshooting

### White Screen Issue (Fixed)
- Improved CSS styling for proper height management
- Better scrolling behavior
- Enhanced container management

### Common Issues
1. **Documentation not loading**: Check if server is running on port 3000
2. **Authentication errors**: Ensure valid token in Authorization header
3. **CORS issues**: Use the built-in proxy for external API calls
4. **Theme not applying**: Clear browser cache and reload

### Development URLs
Replace `localhost:3000` with your actual server URL when deployed.

## 📞 Support

For API support and questions:
- **Email**: support@corradaf.com
- **Documentation**: This interactive documentation
- **Postman Collection**: Available in project root

---

**Note**: This documentation is automatically updated with server information and includes all implemented endpoints from the codebase.