Add comprehensive Swagger/OpenAPI documentation with detailed endpoint descriptions

API_DOCS.md

@@ -0,0 +1,320 @@
+# API Documentation - Vocal Articulation Assessment v2.0
+
+## Swagger/OpenAPI Documentation
+
+API ini menggunakan **FastAPI** yang menyediakan dokumentasi interaktif otomatis.
+
+### Akses Dokumentasi
+
+Setelah aplikasi berjalan, akses dokumentasi di:
+
+#### 1. **Swagger UI** (Recommended)
+```
+https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/docs
+```
+atau lokal:
+```
+http://localhost:7860/docs
+```
+
+**Features:**
+- 🎯 Interactive API testing
+- 📝 Try out endpoints langsung dari browser
+- 📋 Request/Response schemas
+- 🔍 Parameter descriptions
+
+#### 2. **ReDoc** (Alternative Documentation)
+```
+https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/redoc
+```
+atau lokal:
+```
+http://localhost:7860/redoc
+```
+
+**Features:**
+- 📚 Clean, readable documentation
+- 🔗 Deep linking
+- 📖 Better for reading
+
+#### 3. **OpenAPI JSON Schema**
+```
+https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/openapi.json
+```
+atau lokal:
+```
+http://localhost:7860/openapi.json
+```
+
+---
+
+## Quick API Overview
+
+### Base URL
+```
+https://huggingface.co/spaces/Cyberlace/latihan-artikulasi
+```
+
+### Endpoints
+
+| Method | Endpoint | Description | Tags |
+|--------|----------|-------------|------|
+| `GET` | `/` | API information | General |
+| `GET` | `/health` | Health check & model status | System |
+| `GET` | `/levels` | List all articulation levels | Articulation |
+| `POST` | `/score` | Score single audio file | Scoring |
+| `POST` | `/batch_score` | Score multiple audio files | Scoring |
+
+---
+
+## Example Usage
+
+### 1. Check Health
+```bash
+curl -X GET "https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/health"
+```
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "model_loaded": true,
+  "device": "cpu",
+  "whisper_model": "openai/whisper-small"
+}
+```
+
+### 2. Get Levels
+```bash
+curl -X GET "https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/levels"
+```
+
+**Response:**
+```json
+{
+  "levels": {
+    "1": {
+      "name": "Vokal Tunggal",
+      "difficulty": "Pemula",
+      "targets": ["A", "I", "U", "E", "O"]
+    },
+    ...
+  },
+  "total_levels": 5
+}
+```
+
+### 3. Score Audio (Python)
+```python
+import requests
+
+# Single file
+url = "https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/score"
+files = {'audio': open('recording.wav', 'rb')}
+data = {'target_text': 'STRATEGI', 'level': 4}
+
+response = requests.post(url, files=files, data=data)
+result = response.json()
+
+print(f"Score: {result['overall_score']}")
+print(f"Grade: {result['grade']}")
+print(f"Transcription: {result['transcription']}")
+print(f"Feedback: {result['feedback']}")
+```
+
+### 4. Score Audio (cURL)
+```bash
+curl -X POST "https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/score" \
+  -F "[email protected]" \
+  -F "target_text=STRATEGI" \
+  -F "level=4"
+```
+
+### 5. Batch Score (Python)
+```python
+import requests
+
+url = "https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/batch_score"
+
+files = [
+    ('audios', open('audio1.wav', 'rb')),
+    ('audios', open('audio2.wav', 'rb')),
+    ('audios', open('audio3.wav', 'rb')),
+]
+
+data = {
+    'target_texts': 'A,I,U',
+    'levels': '1,1,1'
+}
+
+response = requests.post(url, files=files, data=data)
+results = response.json()['results']
+
+for r in results:
+    print(f"{r['filename']}: Score={r['overall_score']}, Grade={r['grade']}")
+```
+
+---
+
+## Response Schema
+
+### Score Response
+```json
+{
+  "success": true,
+  "overall_score": 85.5,
+  "grade": "B",
+  "clarity_score": 90.0,
+  "energy_score": 85.0,
+  "speech_rate_score": 80.0,
+  "pitch_consistency_score": 88.0,
+  "snr_score": 82.0,
+  "articulation_score": 87.0,
+  "transcription": "STRATEGI",
+  "target": "STRATEGI",
+  "similarity": 1.0,
+  "wer": 0.0,
+  "feedback": "Bagus! Pengucapan sudah cukup jelas.",
+  "suggestions": [
+    "Pertahankan volume suara yang stabil"
+  ],
+  "audio_features": {
+    "duration": 1.234,
+    "rms_db": -25.5,
+    "zero_crossing_rate": 0.0523,
+    "spectral_centroid": 2500.0,
+    "spectral_rolloff": 5000.0,
+    "spectral_bandwidth": 1800.0,
+    "tempo": 120.0
+  },
+  "level": 4
+}
+```
+
+### Grading System
+- **Grade A** (90-100): Sempurna - pengucapan sangat jelas dan akurat
+- **Grade B** (80-89): Bagus - pengucapan cukup jelas dengan minor errors
+- **Grade C** (70-79): Cukup - ada beberapa kesalahan
+- **Grade D** (60-69): Kurang - perlu latihan lebih
+- **Grade E** (<60): Terus berlatih!
+
+### Scoring Metrics
+1. **Clarity** (0-100): ASR accuracy dari Whisper transcription
+2. **Energy** (0-100): Kualitas volume dan energi suara (optimal: -30 to -10 dB)
+3. **Speech Rate** (0-100): Kecepatan bicara (suku kata per detik)
+4. **Pitch Consistency** (0-100): Stabilitas nada suara
+5. **SNR** (0-100): Signal-to-Noise Ratio (kualitas rekaman)
+6. **Articulation** (0-100): Kejernihan artikulasi dari analisis spektral
+
+---
+
+## Error Handling
+
+### Common Errors
+
+**503 Service Unavailable**
+```json
+{
+  "detail": "Model not loaded"
+}
+```
+*Solution*: Tunggu model selesai loading (~30-60 detik saat startup)
+
+**400 Bad Request - Invalid Level**
+```json
+{
+  "detail": "Invalid level. Must be 1-5. Available levels: [1, 2, 3, 4, 5]"
+}
+```
+*Solution*: Gunakan level 1-5
+
+**400 Bad Request - Empty Target**
+```json
+{
+  "detail": "target_text cannot be empty"
+}
+```
+*Solution*: Berikan target_text yang valid
+
+**500 Internal Server Error**
+```json
+{
+  "detail": "Error processing audio: [error message]"
+}
+```
+*Solution*: Pastikan format audio valid (WAV, MP3, M4A, FLAC, OGG)
+
+---
+
+## Testing with Swagger UI
+
+1. Buka: https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/docs
+2. Click endpoint yang ingin di-test (misal: `POST /score`)
+3. Click **"Try it out"**
+4. Fill parameters:
+   - `audio`: Upload file audio
+   - `target_text`: Masukkan text (misal: "STRATEGI")
+   - `level`: Pilih 1-5
+5. Click **"Execute"**
+6. Lihat response di bawah
+
+---
+
+## Client Libraries
+
+### Python
+```python
+# Install requests
+pip install requests
+
+# Example code above
+```
+
+### JavaScript/Node.js
+```javascript
+const FormData = require('form-data');
+const fs = require('fs');
+const axios = require('axios');
+
+const form = new FormData();
+form.append('audio', fs.createReadStream('recording.wav'));
+form.append('target_text', 'STRATEGI');
+form.append('level', '4');
+
+axios.post('https://huggingface.co/spaces/Cyberlace/latihan-artikulasi/score', form, {
+  headers: form.getHeaders()
+})
+.then(response => {
+  console.log('Score:', response.data.overall_score);
+  console.log('Grade:', response.data.grade);
+})
+.catch(error => console.error(error));
+```
+
+### cURL
+```bash
+# See examples above
+```
+
+---
+
+## Rate Limits & Performance
+
+- **Model**: Whisper Small (~967 MB)
+- **Processing Time**: ~2-5 seconds per audio file
+- **Max Audio Duration**: Recommended < 10 seconds for best results
+- **Supported Formats**: WAV, MP3, M4A, FLAC, OGG
+- **Max File Size**: Recommended < 10 MB
+
+---
+
+## Support & Contact
+
+- **HuggingFace Space**: https://huggingface.co/spaces/Cyberlace/latihan-artikulasi
+- **Issues**: Report di HuggingFace Discussions
+- **Version**: 2.0.0
+- **License**: MIT
+
+---
+
+**Last Updated**: November 19, 2025

api/routes.py

@@ -22,8 +22,40 @@ from core.constants import ARTICULATION_LEVELS
 
 app = FastAPI(
     title="Vocal Articulation Assessment API v2",
-    description="API untuk penilaian artikulasi vokal Indonesia - Multi-level dengan Whisper ASR",
-    version="2.0.0"
+    description="""
+    ## API untuk Penilaian Artikulasi Vokal Indonesia
+    
+    Sistem penilaian berbasis **Whisper ASR** dengan analisis audio komprehensif untuk 5 level artikulasi.
+    
+    ### Features
+    - **ASR-based Clarity Scoring** menggunakan Whisper model
+    - **6 Metrik Komprehensif**: Clarity, Energy, Speech Rate, Pitch Consistency, SNR, Articulation
+    - **Multi-level Support**: Level 1-5 (Vokal → Kalimat)
+    - **Grading System**: A-E berdasarkan overall score
+    
+    ### Documentation
+    - **Swagger UI**: `/docs` (interactive API testing)
+    - **ReDoc**: `/redoc` (alternative documentation)
+    - **OpenAPI JSON**: `/openapi.json`
+    
+    ### Endpoints
+    - `GET /` - API information
+    - `GET /health` - Health check & model status
+    - `GET /levels` - List all articulation levels
+    - `POST /score` - Score single audio file
+    - `POST /batch_score` - Score multiple audio files
+    """,
+    version="2.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+    contact={
+        "name": "Vocal Articulation Assessment Team",
+        "url": "https://huggingface.co/spaces/Cyberlace/latihan-artikulasi",
+    },
+    license_info={
+        "name": "MIT License",
+    }
 )
 
 # CORS middleware
@@ -139,9 +171,19 @@ async def root():
         media_type="application/json"
     )
 
-@app.get("/health", response_model=HealthResponse)
+@app.get("/health", response_model=HealthResponse, tags=["System"])
 async def health_check():
-    """Health check endpoint"""
+    """
+    ## Health Check
+    
+    Check API health status and model loading status.
+    
+    **Returns:**
+    - `status`: "healthy" or "unhealthy"
+    - `model_loaded`: Whether Whisper model is loaded
+    - `device`: CPU or CUDA
+    - `whisper_model`: Model name
+    """
     return HealthResponse(
         status="healthy" if scorer is not None else "unhealthy",
         model_loaded=scorer is not None,
@@ -149,27 +191,69 @@ async def health_check():
         whisper_model="openai/whisper-small" if scorer else "not loaded"
     )
 
-@app.get("/levels", response_model=LevelsResponse)
+@app.get("/levels", response_model=LevelsResponse, tags=["Articulation"])
 async def get_levels():
-    """Get all articulation levels and their targets"""
+    """
+    ## Get Articulation Levels
+    
+    Retrieve all available articulation levels with their targets.
+    
+    **Levels:**
+    - **Level 1**: Vokal Tunggal (A, I, U, E, O)
+    - **Level 2**: Konsonan + Vokal (BA, DA, KA, etc.)
+    - **Level 3**: Suku Kata Kompleks (BRA, TRI, etc.)
+    - **Level 4**: Kata Penuh (RUMAH, STRATEGI, etc.)
+    - **Level 5**: Kalimat Lengkap
+    
+    **Returns:**
+    - `levels`: Dictionary of all levels with targets
+    - `total_levels`: Total number of levels (5)
+    """
     return LevelsResponse(
         levels=ARTICULATION_LEVELS,
         total_levels=len(ARTICULATION_LEVELS)
     )
 
-@app.post("/score", response_class=JSONResponse)
+@app.post("/score", response_class=JSONResponse, tags=["Scoring"])
 async def score_audio(
-    audio: UploadFile = File(..., description="Audio file (WAV, MP3, M4A, etc.)"),
+    audio: UploadFile = File(..., description="Audio file (WAV, MP3, M4A, FLAC, OGG)"),
     target_text: str = Form(..., description="Target text yang seharusnya diucapkan"),
     level: int = Form(1, description="Level artikulasi (1-5)")
 ):
     """
-    Score audio file untuk penilaian artikulasi vokal
+    ## Score Audio File
+    
+    Upload audio dan dapatkan penilaian artikulasi vokal komprehensif.
+    
+    **Request:**
+    - `audio`: Audio file (format: WAV, MP3, M4A, FLAC, OGG)
+    - `target_text`: Text yang seharusnya diucapkan (contoh: "A", "BA", "STRATEGI")
+    - `level`: Level artikulasi (1-5)
     
-    Args:
-        audio: File audio yang akan dinilai
-        target_text: Text target yang seharusnya diucapkan
-        level: Level artikulasi (1=Vokal, 2=Konsonan, 3=Suku Kata, 4=Kata, 5=Kalimat)
+    **Response:**
+    - `success`: Boolean status
+    - `overall_score`: Skor keseluruhan (0-100)
+    - `grade`: Grade (A-E)
+    - 6 component scores (clarity, energy, speech_rate, pitch_consistency, snr, articulation)
+    - `transcription`: Hasil ASR dari audio
+    - `target`: Target text (uppercase)
+    - `similarity`: Similarity score (0-1)
+    - `wer`: Word Error Rate (0-1)
+    - `feedback`: Feedback teks
+    - `suggestions`: List saran perbaikan
+    - `audio_features`: Dictionary fitur audio
+    - `level`: Level yang digunakan
+    
+    **Example:**
+    ```python
+    import requests
+    
+    files = {'audio': open('recording.wav', 'rb')}
+    data = {'target_text': 'STRATEGI', 'level': 4}
+    response = requests.post('http://localhost:8000/score', files=files, data=data)
+    result = response.json()
+    print(f"Score: {result['overall_score']}, Grade: {result['grade']}")
+    ```
         
     Returns:
         ScoreResponse dengan hasil penilaian lengkap
@@ -225,22 +309,43 @@ async def score_audio(
         
         raise HTTPException(status_code=500, detail=f"Error processing audio: {str(e)}")
 
-@app.post("/batch_score")
+@app.post("/batch_score", tags=["Scoring"])
 async def batch_score_audio(
     audios: List[UploadFile] = File(..., description="Multiple audio files"),
     target_texts: str = Form(..., description="Comma-separated target texts"),
     levels: str = Form("1", description="Comma-separated levels (default: 1 for all)")
 ):
     """
-    Score multiple audio files dalam satu request
+    ## Batch Score Multiple Audio Files
     
-    Args:
-        audios: List of audio files
-        target_texts: Comma-separated target texts
-        levels: Comma-separated levels (optional, default 1 for all)
-        
-    Returns:
-        List of score results
+    Upload beberapa audio files sekaligus dan dapatkan penilaian untuk masing-masing.
+    
+    **Request:**
+    - `audios`: List of audio files
+    - `target_texts`: Comma-separated target texts (contoh: "A,I,U,E,O")
+    - `levels`: Comma-separated levels (contoh: "1,1,1,2,2") atau single value untuk semua
+    
+    **Response:**
+    - `results`: Array of score results (sama seperti /score endpoint)
+    - `total`: Total number of processed files
+    
+    **Example:**
+    ```python
+    import requests
+    
+    files = [
+        ('audios', open('audio1.wav', 'rb')),
+        ('audios', open('audio2.wav', 'rb')),
+    ]
+    data = {
+        'target_texts': 'A,I',
+        'levels': '1,1'
+    }
+    response = requests.post('http://localhost:8000/batch_score', files=files, data=data)
+    results = response.json()['results']
+    for r in results:
+        print(f"{r['filename']}: {r['overall_score']}")
+    ```
     """
     if scorer is None:
         raise HTTPException(status_code=503, detail="Model not loaded")