Initial commit - Current state of vip-coordinator
This commit is contained in:
218
frontend/public/README-API.md
Normal file
218
frontend/public/README-API.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# VIP Coordinator API Documentation
|
||||
|
||||
## 📚 Overview
|
||||
|
||||
This document provides comprehensive API documentation for the VIP Coordinator system using **OpenAPI 3.0** (Swagger) specification. The API enables management of VIP transportation coordination, including flight tracking, driver management, and event scheduling.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### View API Documentation
|
||||
|
||||
1. **Interactive Documentation (Recommended):**
|
||||
```bash
|
||||
# Open the interactive Swagger UI documentation
|
||||
open vip-coordinator/api-docs.html
|
||||
```
|
||||
Or visit: `file:///path/to/vip-coordinator/api-docs.html`
|
||||
|
||||
2. **Raw OpenAPI Specification:**
|
||||
```bash
|
||||
# View the YAML specification file
|
||||
cat vip-coordinator/api-documentation.yaml
|
||||
```
|
||||
|
||||
### Test the API
|
||||
|
||||
The interactive documentation includes a "Try it out" feature that allows you to test endpoints directly:
|
||||
|
||||
1. Open `api-docs.html` in your browser
|
||||
2. Click on any endpoint to expand it
|
||||
3. Click "Try it out" button
|
||||
4. Fill in parameters and request body
|
||||
5. Click "Execute" to make the API call
|
||||
|
||||
## 📋 API Categories
|
||||
|
||||
### 🏥 Health
|
||||
- `GET /api/health` - System health check
|
||||
|
||||
### 👥 VIPs
|
||||
- `GET /api/vips` - Get all VIPs
|
||||
- `POST /api/vips` - Create new VIP
|
||||
- `PUT /api/vips/{id}` - Update VIP
|
||||
- `DELETE /api/vips/{id}` - Delete VIP
|
||||
|
||||
### 🚗 Drivers
|
||||
- `GET /api/drivers` - Get all drivers
|
||||
- `POST /api/drivers` - Create new driver
|
||||
- `PUT /api/drivers/{id}` - Update driver
|
||||
- `DELETE /api/drivers/{id}` - Delete driver
|
||||
- `GET /api/drivers/{driverId}/schedule` - Get driver's schedule
|
||||
- `POST /api/drivers/availability` - Check driver availability
|
||||
- `POST /api/drivers/{driverId}/conflicts` - Check driver conflicts
|
||||
|
||||
### ✈️ Flights
|
||||
- `GET /api/flights/{flightNumber}` - Get flight information
|
||||
- `POST /api/flights/{flightNumber}/track` - Start flight tracking
|
||||
- `DELETE /api/flights/{flightNumber}/track` - Stop flight tracking
|
||||
- `POST /api/flights/batch` - Get multiple flights info
|
||||
- `GET /api/flights/tracking/status` - Get tracking status
|
||||
|
||||
### 📅 Schedule
|
||||
- `GET /api/vips/{vipId}/schedule` - Get VIP's schedule
|
||||
- `POST /api/vips/{vipId}/schedule` - Add event to schedule
|
||||
- `PUT /api/vips/{vipId}/schedule/{eventId}` - Update event
|
||||
- `DELETE /api/vips/{vipId}/schedule/{eventId}` - Delete event
|
||||
- `PATCH /api/vips/{vipId}/schedule/{eventId}/status` - Update event status
|
||||
|
||||
### ⚙️ Admin
|
||||
- `POST /api/admin/authenticate` - Admin authentication
|
||||
- `GET /api/admin/settings` - Get admin settings
|
||||
- `POST /api/admin/settings` - Update admin settings
|
||||
|
||||
## 💡 Example API Calls
|
||||
|
||||
### Create a VIP with Flight
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/vips \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "John Doe",
|
||||
"organization": "Tech Corp",
|
||||
"transportMode": "flight",
|
||||
"flights": [
|
||||
{
|
||||
"flightNumber": "UA1234",
|
||||
"flightDate": "2025-06-26",
|
||||
"segment": 1
|
||||
}
|
||||
],
|
||||
"needsAirportPickup": true,
|
||||
"needsVenueTransport": true,
|
||||
"notes": "CEO - requires executive transport"
|
||||
}'
|
||||
```
|
||||
|
||||
### Add Event to VIP Schedule
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/vips/{vipId}/schedule \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "Meeting with CEO",
|
||||
"location": "Hyatt Regency Denver",
|
||||
"startTime": "2025-06-26T11:00:00",
|
||||
"endTime": "2025-06-26T12:30:00",
|
||||
"type": "meeting",
|
||||
"assignedDriverId": "1748780965562",
|
||||
"description": "Important strategic meeting"
|
||||
}'
|
||||
```
|
||||
|
||||
### Check Driver Availability
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/drivers/availability \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"startTime": "2025-06-26T11:00:00",
|
||||
"endTime": "2025-06-26T12:30:00",
|
||||
"location": "Denver Convention Center"
|
||||
}'
|
||||
```
|
||||
|
||||
### Get Flight Information
|
||||
```bash
|
||||
curl "http://localhost:3000/api/flights/UA1234?date=2025-06-26"
|
||||
```
|
||||
|
||||
## 🔧 Tools for API Documentation
|
||||
|
||||
### 1. **Swagger UI (Recommended)**
|
||||
- **What it is:** Interactive web-based API documentation
|
||||
- **Features:**
|
||||
- Try endpoints directly in browser
|
||||
- Auto-generated from OpenAPI spec
|
||||
- Beautiful, responsive interface
|
||||
- Request/response examples
|
||||
- **Access:** Open `api-docs.html` in your browser
|
||||
|
||||
### 2. **OpenAPI Specification**
|
||||
- **What it is:** Industry-standard API specification format
|
||||
- **Features:**
|
||||
- Machine-readable API definition
|
||||
- Can generate client SDKs
|
||||
- Supports validation and testing
|
||||
- Compatible with many tools
|
||||
- **File:** `api-documentation.yaml`
|
||||
|
||||
### 3. **Alternative Tools**
|
||||
|
||||
You can use the OpenAPI specification with other tools:
|
||||
|
||||
#### Postman
|
||||
1. Import `api-documentation.yaml` into Postman
|
||||
2. Automatically creates a collection with all endpoints
|
||||
3. Includes examples and validation
|
||||
|
||||
#### Insomnia
|
||||
1. Import the OpenAPI spec
|
||||
2. Generate requests automatically
|
||||
3. Built-in environment management
|
||||
|
||||
#### VS Code Extensions
|
||||
- **OpenAPI (Swagger) Editor** - Edit and preview API specs
|
||||
- **REST Client** - Test APIs directly in VS Code
|
||||
|
||||
## 📖 Documentation Best Practices
|
||||
|
||||
### Why OpenAPI/Swagger?
|
||||
|
||||
1. **Industry Standard:** Most widely adopted API documentation format
|
||||
2. **Interactive:** Users can test APIs directly in the documentation
|
||||
3. **Code Generation:** Can generate client libraries in multiple languages
|
||||
4. **Validation:** Ensures API requests/responses match specification
|
||||
5. **Tooling:** Extensive ecosystem of tools and integrations
|
||||
|
||||
### Documentation Features
|
||||
|
||||
- **Comprehensive:** All endpoints, parameters, and responses documented
|
||||
- **Examples:** Real-world examples for all operations
|
||||
- **Schemas:** Detailed data models with validation rules
|
||||
- **Error Handling:** Clear error response documentation
|
||||
- **Authentication:** Security requirements clearly specified
|
||||
|
||||
## 🔗 Integration Examples
|
||||
|
||||
### Frontend Integration
|
||||
```javascript
|
||||
// Example: Fetch VIPs in React
|
||||
const fetchVips = async () => {
|
||||
const response = await fetch('/api/vips');
|
||||
const vips = await response.json();
|
||||
return vips;
|
||||
};
|
||||
```
|
||||
|
||||
### Backend Integration
|
||||
```bash
|
||||
# Example: Using curl to test endpoints
|
||||
curl -X GET http://localhost:3000/api/health
|
||||
curl -X GET http://localhost:3000/api/vips
|
||||
curl -X GET http://localhost:3000/api/drivers
|
||||
```
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **Explore the Interactive Docs:** Open `api-docs.html` and try the endpoints
|
||||
2. **Test with Real Data:** Use the populated test data to explore functionality
|
||||
3. **Build Integrations:** Use the API specification to build client applications
|
||||
4. **Extend the API:** Add new endpoints following the established patterns
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For questions about the API:
|
||||
- Review the interactive documentation
|
||||
- Check the OpenAPI specification for detailed schemas
|
||||
- Test endpoints using the "Try it out" feature
|
||||
- Refer to the example requests and responses
|
||||
|
||||
The API documentation is designed to be self-service and comprehensive, providing everything needed to integrate with the VIP Coordinator system.
|
||||
148
frontend/public/api-docs.html
Normal file
148
frontend/public/api-docs.html
Normal file
@@ -0,0 +1,148 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>VIP Coordinator API Documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css" />
|
||||
<style>
|
||||
html {
|
||||
box-sizing: border-box;
|
||||
overflow: -moz-scrollbars-vertical;
|
||||
overflow-y: scroll;
|
||||
}
|
||||
*, *:before, *:after {
|
||||
box-sizing: inherit;
|
||||
}
|
||||
body {
|
||||
margin:0;
|
||||
background: #fafafa;
|
||||
}
|
||||
.swagger-ui .topbar {
|
||||
background-color: #3498db;
|
||||
}
|
||||
.swagger-ui .topbar .download-url-wrapper .select-label {
|
||||
color: white;
|
||||
}
|
||||
.swagger-ui .topbar .download-url-wrapper input[type=text] {
|
||||
border: 2px solid #2980b9;
|
||||
}
|
||||
.swagger-ui .info .title {
|
||||
color: #2c3e50;
|
||||
}
|
||||
.custom-header {
|
||||
background: linear-gradient(135deg, #3498db, #2980b9);
|
||||
color: white;
|
||||
padding: 20px;
|
||||
text-align: center;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
.custom-header h1 {
|
||||
margin: 0;
|
||||
font-size: 2.5em;
|
||||
font-weight: 300;
|
||||
}
|
||||
.custom-header p {
|
||||
margin: 10px 0 0 0;
|
||||
font-size: 1.2em;
|
||||
opacity: 0.9;
|
||||
}
|
||||
.quick-links {
|
||||
background: white;
|
||||
padding: 20px;
|
||||
margin: 20px;
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
|
||||
}
|
||||
.quick-links h3 {
|
||||
color: #2c3e50;
|
||||
margin-top: 0;
|
||||
}
|
||||
.quick-links ul {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
|
||||
gap: 10px;
|
||||
}
|
||||
.quick-links li {
|
||||
background: #ecf0f1;
|
||||
padding: 10px 15px;
|
||||
border-radius: 5px;
|
||||
border-left: 4px solid #3498db;
|
||||
}
|
||||
.quick-links li strong {
|
||||
color: #2c3e50;
|
||||
}
|
||||
.quick-links li code {
|
||||
background: #34495e;
|
||||
color: white;
|
||||
padding: 2px 6px;
|
||||
border-radius: 3px;
|
||||
font-size: 0.9em;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="custom-header">
|
||||
<h1>🚗 VIP Coordinator API</h1>
|
||||
<p>Comprehensive API for managing VIP transportation coordination</p>
|
||||
</div>
|
||||
|
||||
<div class="quick-links">
|
||||
<h3>🚀 Quick Start Examples</h3>
|
||||
<ul>
|
||||
<li><strong>Health Check:</strong> <code>GET /api/health</code></li>
|
||||
<li><strong>Get All VIPs:</strong> <code>GET /api/vips</code></li>
|
||||
<li><strong>Get All Drivers:</strong> <code>GET /api/drivers</code></li>
|
||||
<li><strong>Flight Info:</strong> <code>GET /api/flights/UA1234?date=2025-06-26</code></li>
|
||||
<li><strong>VIP Schedule:</strong> <code>GET /api/vips/{vipId}/schedule</code></li>
|
||||
<li><strong>Driver Availability:</strong> <code>POST /api/drivers/availability</code></li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div id="swagger-ui"></div>
|
||||
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js"></script>
|
||||
<script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-standalone-preset.js"></script>
|
||||
<script>
|
||||
window.onload = function() {
|
||||
// Begin Swagger UI call region
|
||||
const ui = SwaggerUIBundle({
|
||||
url: '/api-documentation.yaml',
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
presets: [
|
||||
SwaggerUIBundle.presets.apis,
|
||||
SwaggerUIStandalonePreset
|
||||
],
|
||||
plugins: [
|
||||
SwaggerUIBundle.plugins.DownloadUrl
|
||||
],
|
||||
layout: "StandaloneLayout",
|
||||
tryItOutEnabled: true,
|
||||
requestInterceptor: function(request) {
|
||||
// Add base URL if not present
|
||||
if (request.url.startsWith('/api/')) {
|
||||
request.url = 'http://localhost:3000' + request.url;
|
||||
}
|
||||
return request;
|
||||
},
|
||||
onComplete: function() {
|
||||
console.log('VIP Coordinator API Documentation loaded successfully!');
|
||||
},
|
||||
docExpansion: 'list',
|
||||
defaultModelsExpandDepth: 2,
|
||||
defaultModelExpandDepth: 2,
|
||||
showExtensions: true,
|
||||
showCommonExtensions: true,
|
||||
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
|
||||
validatorUrl: null
|
||||
});
|
||||
// End Swagger UI call region
|
||||
|
||||
window.ui = ui;
|
||||
};
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
1189
frontend/public/api-documentation.yaml
Normal file
1189
frontend/public/api-documentation.yaml
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user