Add simple API documentation endpoint

 Added Simple API Documentation:
- Created API_DOCS.md with comprehensive endpoint documentation
- Added /docs endpoint to serve formatted API documentation
- Updated /api endpoint to include documentation reference
- Simple HTML formatting for better readability

 Documentation Features:
- Complete endpoint descriptions with examples
- Request/response formats for all endpoints
- cURL and Python usage examples
- Error response documentation
- Model information and specifications

 Access Points:
- /api - Basic API info (JSON)
- /docs - Detailed documentation (HTML)
- API_DOCS.md - Raw markdown documentation

Simple, clean documentation without complex Swagger UI overhead.
This commit is contained in:
Aherobo Ovie Victor
2025-07-12 07:45:56 +01:00
parent 2426e71ed0
commit 0b7af4050e
2 changed files with 255 additions and 1 deletions
+214
View File
@@ -0,0 +1,214 @@
# Memory Module Detection API Documentation
## Base URL
```
http://localhost:5002
```
## Endpoints
### 1. Health Check
**GET** `/health`
Check if the API is running and model is loaded.
**Response:**
```json
{
"status": "healthy",
"model_loaded": true,
"timestamp": "2025-07-12T07:41:46.123456"
}
```
### 2. API Information
**GET** `/api`
Get basic API information and available endpoints.
**Response:**
```json
{
"name": "Memory Module Detection API",
"version": "1.0",
"description": "AI-powered memory module detection using YOLOv8",
"model_loaded": true,
"endpoints": ["/health", "/api", "/detect", "/detect/hardcoded", "/detect/base64"]
}
```
### 3. Upload Image Detection
**POST** `/detect`
Upload an image file for memory module detection.
**Request:**
- Content-Type: `multipart/form-data`
- Body: Form data with `file` field containing image
- Optional: `confidence` parameter (default: 0.8)
**Response:**
```json
{
"success": true,
"detections": [
{
"x1": 100.5,
"y1": 150.2,
"x2": 200.8,
"y2": 250.6,
"confidence": 0.95,
"class": "memory_module"
}
],
"num_detections": 1,
"annotated_image": "base64_encoded_image_string",
"confidence_threshold": 0.8
}
```
### 4. Hardcoded Test Image
**GET** `/detect/hardcoded`
Process the hardcoded test image for detection.
**Query Parameters:**
- `confidence` (optional): Confidence threshold (default: 0.8)
**Example:**
```
GET /detect/hardcoded?confidence=0.9
```
**Response:**
```json
{
"success": true,
"detections": [...],
"num_detections": 2,
"annotated_image": "base64_encoded_image_string",
"confidence_threshold": 0.9,
"test_image_path": "training/memory/out1.png"
}
```
### 5. Base64 Image Detection
**POST** `/detect/base64`
Process a base64 encoded image for detection.
**Request:**
```json
{
"image_data": "base64_encoded_image_string",
"confidence": 0.8
}
```
**Response:**
```json
{
"success": true,
"detections": [...],
"num_detections": 1,
"annotated_image": "base64_encoded_image_string",
"confidence_threshold": 0.8
}
```
## Error Responses
All endpoints return error responses in this format:
```json
{
"error": "Error message description",
"success": false
}
```
Common HTTP status codes:
- `200` - Success
- `400` - Bad Request (invalid file, missing parameters)
- `404` - Not Found (endpoint or file not found)
- `413` - File Too Large (max 16MB)
- `500` - Internal Server Error (model not loaded, processing error)
## Supported Image Formats
- PNG
- JPG/JPEG
- GIF
- BMP
## File Size Limits
- Maximum upload size: 16MB
## Detection Response Format
Each detection object contains:
- `x1, y1`: Top-left corner coordinates
- `x2, y2`: Bottom-right corner coordinates
- `confidence`: Detection confidence score (0.0-1.0)
- `class`: Detected object class ("memory_module")
## Usage Examples
### cURL Examples
**Health Check:**
```bash
curl http://localhost:5002/health
```
**Upload Image:**
```bash
curl -X POST -F "file=@image.jpg" -F "confidence=0.8" http://localhost:5002/detect
```
**Hardcoded Test:**
```bash
curl "http://localhost:5002/detect/hardcoded?confidence=0.9"
```
### Python Examples
**Health Check:**
```python
import requests
response = requests.get('http://localhost:5002/health')
print(response.json())
```
**Upload Image:**
```python
import requests
with open('image.jpg', 'rb') as f:
files = {'file': f}
data = {'confidence': 0.8}
response = requests.post('http://localhost:5002/detect', files=files, data=data)
print(response.json())
```
**Base64 Detection:**
```python
import requests
import base64
with open('image.jpg', 'rb') as f:
image_data = base64.b64encode(f.read()).decode()
payload = {
'image_data': image_data,
'confidence': 0.8
}
response = requests.post('http://localhost:5002/detect/base64', json=payload)
print(response.json())
```
## Model Information
- **Architecture:** YOLOv8 Nano
- **Classes:** memory_module
- **Input Size:** 640x640
- **Accuracy:** 99.5% mAP50
- **Inference Time:** ~37ms on CPU
+41 -1
View File
@@ -88,16 +88,56 @@ def api_info():
'endpoints': { 'endpoints': {
'/': 'GET - Frontend interface or API information', '/': 'GET - Frontend interface or API information',
'/api': 'GET - API information (JSON)', '/api': 'GET - API information (JSON)',
'/docs': 'GET - Detailed API documentation',
'/detect': 'POST - Upload image for memory module detection', '/detect': 'POST - Upload image for memory module detection',
'/detect/hardcoded': 'GET - Process hardcoded test image', '/detect/hardcoded': 'GET - Process hardcoded test image',
'/detect/base64': 'POST - Process base64 encoded image', '/detect/base64': 'POST - Process base64 encoded image',
'/health': 'GET - Health check' '/health': 'GET - Health check'
}, },
'model_loaded': detector.model is not None, 'model_loaded': detector.model is not None,
'supported_formats': list(ALLOWED_EXTENSIONS) 'supported_formats': list(ALLOWED_EXTENSIONS),
'documentation': 'Visit /docs for detailed API documentation'
}) })
@app.route('/docs')
def api_docs():
"""Serve API documentation."""
try:
with open('API_DOCS.md', 'r') as f:
docs_content = f.read()
# Convert markdown to HTML for better display
html_content = f"""
<!DOCTYPE html>
<html>
<head>
<title>Memory Module Detection API - Documentation</title>
<style>
body {{ font-family: Arial, sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; line-height: 1.6; }}
pre {{ background: #f4f4f4; padding: 15px; border-radius: 5px; overflow-x: auto; }}
code {{ background: #f4f4f4; padding: 2px 4px; border-radius: 3px; }}
h1, h2, h3 {{ color: #333; }}
.nav {{ background: #e8f5e8; padding: 10px; margin-bottom: 20px; border-radius: 5px; }}
.nav a {{ margin-right: 15px; text-decoration: none; color: #0066cc; }}
.nav a:hover {{ text-decoration: underline; }}
</style>
</head>
<body>
<div class="nav">
<a href="/">🏠 Web Interface</a>
<a href="/api">📊 API Info</a>
<a href="/health">💚 Health Check</a>
</div>
<pre>{docs_content}</pre>
</body>
</html>
"""
return html_content
except FileNotFoundError:
return jsonify({
'error': 'API documentation file not found',
'message': 'Please ensure API_DOCS.md exists in the project directory'
}), 404
@app.route('/health', methods=['GET']) @app.route('/health', methods=['GET'])
def health_check(): def health_check():