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:
+214
@@ -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
|
||||||
@@ -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():
|
||||||
|
|||||||
Reference in New Issue
Block a user