# MangoApps API Documentation

This directory contains the MangoApps API documentation with **custom branding that exactly matches [dev.workforce.mangoapps.com](https://dev.workforce.mangoapps.com)**.

## 🎯 Perfect Brand Consistency

The API documentation uses the **identical header, footer, colors, and styling** as the MangoApps marketing site, providing a seamless user experience across the entire platform.

## 📁 File Structure

- `index.html` - Main documentation page (custom MangoApps theme)
- `config.js` - Configuration for branding and features  
- `mangoops-theme.css` - Custom CSS styling
- `v1/openapi.yaml` - OpenAPI specification (auto-generated)
- `v1/openapi.json` - JSON version of spec (auto-generated)
- `openapi.yaml` / `openapi.json` - byte-identical mirrors of the `v1/` files (auto-generated in the same run). This root path is what external consumers are given — the `/openapi.json`, `/openapi.yaml`, `/api/openapi.*` redirects in `config/routes.rb`, the public developer pages, `.well-known/mcp.json` and `/llms.txt` all point here — while the Swagger UI (`config.js`) reads `v1/`. Never update the root copies by hand; run `swagger:generate`.
- `CUSTOMIZATION.md` - Detailed customization guide

## 🔄 Updating Documentation

The rake tasks are designed to **preserve your custom branding and styling**:

### Update API Specification Only
Updates only the OpenAPI YAML/JSON files, preserves all custom UI:
```bash
docker-compose exec ma-shifts-ror bundle exec rails swagger:generate
```

### Complete Documentation Regeneration 
Regenerates specs + creates UI files only if missing (preserves existing customizations):
```bash
docker-compose exec ma-shifts-ror bundle exec rails swagger:docs
```

### Reset UI to Default Template
**⚠️ DANGER**: This will overwrite your custom index.html, CSS, and JS files:
```bash
docker-compose exec ma-shifts-ror bundle exec rails swagger:reset_ui
```

## 🛡️ Customization Protection

Your `index.html`, `config.js`, `mangoops-theme.css`, and other custom files will **NEVER** be overwritten by `swagger:generate` or `swagger:docs`. Only the OpenAPI specification files (`v1/openapi.yaml`, `v1/openapi.json` and their root mirrors `openapi.yaml`, `openapi.json`) are updated automatically.

## 🎨 Safe Customization

### Quick Color Changes
Edit `config.js`:
```javascript
theme: {
    primary: '#4285f4',      // Bootstrap primary blue from MangoApps
    secondary: '#34a853'     // Green accent from MangoApps gradient
}
```

### Update Branding
Edit `config.js`:
```javascript
branding: {
    title: "Your API Name",
    company: "Your Company"
}
```

### Styling Changes
Edit `mangoops-theme.css` for advanced styling modifications.

See `CUSTOMIZATION.md` for detailed customization guide.

## 🌐 Access URLs

- **Local**: http://localhost:3001/api-docs/index.html
- **Production**: https://officechat-dev.workforce.mangoapps.com/api-docs/index.html

## 🚀 API Documentation Features

- **Interactive Documentation**: Swagger UI with MangoApps branding
- **OpenAPI 3.0.3**: Modern specification format
- **Test Mode**: Built-in API testing with authentication
- **Responsive Design**: Works perfectly on all devices

## 🔐 Authentication Methods

### 1. Mobile App Authentication
```bash
POST /api/v1/auth/login
{
  "email": "user@example.com", 
  "password": "password",
  "otp_code": "123456"  // Optional, for 2FA
}
```

### 2. API Token Authentication
```bash
Authorization: Bearer YOUR_API_TOKEN
```

### 3. Service Account Authentication  
```bash
Authorization: Bearer YOUR_TOKEN
X-API-Secret: YOUR_SECRET
```

## 📋 Base URL

```
https://officechat-dev.workforce.mangoapps.com/api/v1/
```

## 🆘 Support

- **API Support**: [api-support@workforce.mangoapps.com](mailto:api-support@workforce.mangoapps.com)
- **MangoApps Platform**: [dev.workforce.mangoapps.com](https://dev.workforce.mangoapps.com)
- **Download Spec**: [openapi.yaml](./v1/openapi.yaml)

---

**© 2025 [MangoApps](https://www.mangoapps.com/operations) | All rights reserved.**