# Story 9.1: Créer l'API publique avec documentation OpenAPI

Status: review

## Acceptance Criteria

**Given** l'API publique est implémentée
**When** je consulte `/docs` (Swagger UI)
**Then** je vois la documentation complète de l'API
**And** tous les endpoints sont documentés avec exemples
**And** je peux tester les endpoints directement depuis la documentation

**Given** je fais une requête à l'API publique
**When** j'utilise une clé API valide
**Then** je reçois les données au format JSON
**And** la réponse suit le format standardisé avec `data` et `meta`

## Tasks / Subtasks

- [x] Créer l'endpoint `/api/public` (AC: #1)
  - [x] Créer `src/app/api/public/v1/` ou `backend/app/api/public/v1/`
  - [x] Créer `GET /api/public/v1/predictions` (public)
  - [x] Créer `GET /api/public/v1/matches` (public)
  - [x] Limiter les données publiques (pas de données sensibles)
  - [x] Documenter les endpoints

- [x] Créer le système d'authentification par clé API (AC: #2)
  - [x] Créer `src/services/apiKeyService.ts` ou `backend/app/services/apiKeyService.py`
  - [x] Créer la table `api_keys` dans Drizzle/SQLAlchemy
  - [x] Créer la fonction `generateApiKey(userId)`
  - [x] Créer la fonction `validateApiKey(apiKey)`
  - [x] Implémenter le rate limiting différencié par clé API

- [x] Configurer la documentation Swagger UI (AC: #1)
  - [x] Configurer FastAPI Swagger UI (`/docs`)
  - [x] Ajouter les descriptions détaillées des endpoints
  - [x] Ajouter les tags pour groupement logique
  - [x] Ajouter les exemples de requêtes/réponses
  - [x] Documenter les codes d'erreur (400, 401, 404, 500)

- [x] Créer les schémas OpenAPI (AC: #1)
  - [x] Créer les schémas Pydantic pour les réponses
  - [x] Utiliser OpenAPI 3.1
  - [x] Définir les formats standardisés (`{data, meta}` et `{error, meta}`)
  - [x] Documenter tous les types
  - [x] Générer la documentation automatique

- [x] Créer l'endpoint `/openapi.json` (AC: #1)
  - [x] Créer `GET /openapi.json` pour exporter le schéma
  - [x] Permettre aux développeurs tiers de récupérer le schéma
  - [x] Valider que le schéma est complet
  - [x] Documenter l'endpoint

- [x] Créer le dashboard pour développeurs (AC: #1)
  - [x] Créer `src/app/(developer)/dashboard/page.tsx`
  - [x] Afficher les statistiques d'utilisation de l'API
  - [x] Afficher la clé API de l'utilisateur
  - [x] Permettre de régénérer la clé API
  - [x] Afficher la documentation OpenAPI

- [x] Créer les tests de l'API publique (AC: #1, #2)
  - [x] Tester les endpoints publics
  - [x] Tester la validation de clé API
  - [x] Tester le rate limiting
  - [x] Tester la documentation Swagger UI
  - [x] Tester le format des réponses

- [x] Protéger l'API publique (AC: #1, #2)
  - [x] Configurer CORS pour autoriser les requêtes externes
  - [x] Configurer le rate limiting par clé API
  - [x] Désactiver `/docs` en production (ou protéger)
  - [x] Logger les requêtes d'API
  - [x] Monitorer l'utilisation

## Dev Notes

### Stack Technique
- **API:** FastAPI avec OpenAPI 3.1
- **Documentation:** Swagger UI + Redoc
- **Auth:** API Keys
- **Rate Limiting:** Par clé API

### File Structure
```
backend/app/
├── api/
│   ├── public/
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── predictions.py
│   │       └── matches.py
├── schemas/
│   └── public.py
└── services/
    └── apiKeyService.py
```

### References
- [Source: _bmad-output/planning-artifacts/epics.md#Story-9.1]

## Dev Agent Record

### Agent Model Used
GLM-4.7

### Completion Notes List
- API publique créée avec succès
- Documentation OpenAPI implémentée
- Système de clés API fonctionnel
- Swagger UI configurée et documentée
- Rate limiting différencié implémenté
- Dashboard développeur créé
- Tests écrits pour l'API publique

### File List
- `backend/app/api/public/__init__.py`
- `backend/app/api/public/v1/__init__.py`
- `backend/app/api/public/v1/predictions.py`
- `backend/app/api/public/v1/matches.py`
- `backend/app/schemas/public.py`
- `backend/app/services/apiKeyService.py`
- `backend/app/models/api_key.py`
- `backend/app/api/dependencies.py`
- `backend/app/middleware/__init__.py`
- `backend/app/middleware/rate_limiter.py`
- `backend/alembic/versions/20260118_0008_create_api_keys_table.py`
- `backend/tests/test_public_api.py`
- `backend/tests/test_api_key_service.py`
- `backend/tests/test_api_dependencies.py`
- `chartbastan/src/app/(developer)/dashboard/page.tsx`
- `backend/app/main.py` (modifié pour inclure routes publiques et middleware)
- `backend/app/models/user.py` (modifié pour ajouter relation api_keys)
- `backend/app/models/__init__.py` (modifié pour exporter ApiKey)