Documentation API avec Swagger/OpenAPI
Theorie 45 min
Pourquoi documenter votre API ?
Une API de modele ML sans documentation est comme un restaurant sans menu — personne ne sait ce qu'il peut commander ni comment.
La documentation API repond a ces questions pour chaque consommateur :
- Quels endpoints sont disponibles ?
- Quelles donnees dois-je envoyer ?
- Qu'est-ce que je recevrai en retour ?
- Quelles erreurs peuvent survenir ?
- Comment m'authentifier ?
Le vrai cout d'une mauvaise documentation
| Sans documentation | Avec documentation |
|---|---|
| Les developpeurs vous envoient un email chaque fois qu'ils veulent utiliser l'API | Libre-service — les developpeurs lisent la doc |
| L'integration prend des jours/semaines | L'integration prend des heures |
| Des bugs causes par des hypotheses incorrectes | Des contrats clairs evitent les malentendus |
| Personne n'utilise votre API (meme si le modele est excellent) | L'adoption se fait sans friction |
| Vous passez 50 % de votre temps a repondre aux questions | Vous passez ce temps a ameliorer le modele |
L'analogie du "menu"
Un menu de restaurant est la documentation API originale :
- Endpoint = Categorie de plats (entrees, plats principaux, desserts)
- Requete = Votre commande (taille, modifications, accompagnements)
- Reponse = Le plat livre
- Code de statut = Retour du serveur ("ca arrive tout de suite !" vs "on n'en a plus")
- Exemples = Photos des plats
Specification OpenAPI
La specification OpenAPI (anciennement specification Swagger) est le standard industriel pour decrire les API REST. C'est un format lisible par les machines (YAML ou JSON) qui decrit completement votre API.
Structure d'un document OpenAPI
Exemple YAML OpenAPI
openapi: 3.1.0
info:
title: ML Prediction API
description: Loan approval prediction service
version: 1.0.0
contact:
name: ML Team
email: ml-team@example.com
servers:
- url: http://localhost:8000
description: Development
- url: https://api.production.com
description: Production
paths:
/api/v1/predict:
post:
summary: Get a loan approval prediction
description: >
Submit loan application features and receive
an approval or denial prediction with confidence score.
tags:
- Predictions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PredictionInput'
example:
age: 35
income: 55000.0
credit_score: 720
employment_years: 8.5
loan_amount: 25000.0
responses:
'200':
description: Successful prediction
content:
application/json:
schema:
$ref: '#/components/schemas/PredictionOutput'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
/health:
get:
summary: Health check
tags:
- System
responses:
'200':
description: Service health status
components:
schemas:
PredictionInput:
type: object
required:
- age
- income
- credit_score
- employment_years
- loan_amount
properties:
age:
type: integer
minimum: 18
maximum: 120
description: Applicant age in years
income:
type: number
minimum: 0
description: Annual income in USD
credit_score:
type: integer
minimum: 300
maximum: 850
description: Credit score (FICO)
employment_years:
type: number
minimum: 0
description: Years of employment
loan_amount:
type: number
minimum: 0
description: Requested loan amount
PredictionOutput:
type: object
properties:
prediction:
type: string
enum: [approved, denied]
probability:
type: number
minimum: 0
maximum: 1
model_version:
type: string
timestamp:
type: string
format: date-time
ErrorResponse:
type: object
properties:
error_code:
type: string
message:
type: string
details:
type: array
items:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- ApiKeyAuth: []
Swagger UI
Swagger UI affiche votre specification OpenAPI sous forme de page web interactive ou les developpeurs peuvent :
- Parcourir tous les endpoints
- Voir les schemas de requete/reponse
- Tester des requetes directement depuis le navigateur
- Visualiser des exemples de payloads
Disposition de Swagger UI
Documentation auto-generee dans FastAPI
FastAPI genere une documentation OpenAPI complete automatiquement a partir de votre code. Aucune configuration supplementaire n'est necessaire.
Comment FastAPI genere la documentation
Voir le flux de documentation automatique FastAPI
Ameliorer la documentation automatique
from fastapi import FastAPI, Query, Path, Body
from pydantic import BaseModel, Field
app = FastAPI(
title="Loan Prediction API",
description="""
## ML-Powered Loan Approval Predictions
This API serves a machine learning model that predicts
whether a loan application will be **approved** or **denied**.
### Features
- Real-time predictions with confidence scores
- Batch prediction support
- Model version tracking
### Authentication
All endpoints require an API key via the `X-API-Key` header.
""",
version="2.0.0",
contact={
"name": "ML Engineering Team",
"email": "ml-team@example.com",
},
license_info={
"name": "MIT",
"url": "https://opensource.org/licenses/MIT",
},
openapi_tags=[
{
"name": "Predictions",
"description": "Submit features and receive ML predictions",
},
{
"name": "Models",
"description": "Manage deployed ML models",
},
{
"name": "System",
"description": "Health checks and service status",
},
],
)
Ajouter des exemples aux schemas
class PredictionInput(BaseModel):
age: int = Field(..., ge=18, le=120, description="Applicant age")
income: float = Field(..., gt=0, description="Annual income (USD)")
credit_score: int = Field(..., ge=300, le=850, description="FICO score")
employment_years: float = Field(..., ge=0, description="Years employed")
loan_amount: float = Field(..., gt=0, description="Loan amount (USD)")
class Config:
json_schema_extra = {
"examples": [
{
"summary": "Strong applicant",
"description": "High income, excellent credit",
"value": {
"age": 42,
"income": 95000,
"credit_score": 780,
"employment_years": 15,
"loan_amount": 30000,
},
},
{
"summary": "Average applicant",
"description": "Moderate income and credit",
"value": {
"age": 28,
"income": 45000,
"credit_score": 650,
"employment_years": 3,
"loan_amount": 15000,
},
},
{
"summary": "Risky applicant",
"description": "Low credit score, new employment",
"value": {
"age": 22,
"income": 28000,
"credit_score": 520,
"employment_years": 0.5,
"loan_amount": 20000,
},
},
]
}
Documenter les codes de reponse
from fastapi import HTTPException
from fastapi.responses import JSONResponse
@app.post(
"/api/v1/predict",
response_model=PredictionOutput,
responses={
200: {
"description": "Successful prediction",
"content": {
"application/json": {
"example": {
"prediction": "approved",
"probability": 0.87,
"model_version": "v2.1",
"timestamp": "2026-02-23T14:30:00Z",
}
}
},
},
422: {
"description": "Validation error — invalid input features",
"content": {
"application/json": {
"example": {
"detail": [
{
"loc": ["body", "credit_score"],
"msg": "ensure this value is >= 300",
"type": "value_error",
}
]
}
}
},
},
503: {
"description": "Model not loaded or unavailable",
},
},
summary="Get loan approval prediction",
description="Submit loan features and receive prediction with confidence.",
tags=["Predictions"],
)
def predict(input_data: PredictionInput):
...
Documentation dans Flask avec Flask-RESTX
Flask necessite des extensions pour la documentation Swagger. Flask-RESTX est le choix le plus populaire.
Configuration de Flask-RESTX
from flask import Flask
from flask_restx import Api, Resource, fields
app = Flask(__name__)
api = Api(
app,
version="1.0",
title="Loan Prediction API",
description="ML-powered loan approval predictions",
doc="/docs",
authorizations={
"apikey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
}
},
)
Comparaison : documentation FastAPI vs Flask-RESTX
| Aspect | FastAPI | Flask-RESTX |
|---|---|---|
| Effort de configuration | Zero (auto-generee) | Modere (definitions de modeles manuelles) |
| Source des schemas | Modeles Pydantic | Definitions api.model() |
| Validation | Automatique depuis le schema | Optionnelle (validate=True) |
| Exemples | Dans la Config Pydantic | Dans les fields ou @api.doc() |
| Interface | Swagger + ReDoc | Swagger uniquement |
| Version OpenAPI | 3.1 | 2.0 (Swagger) |
| Maintenance | Schemas = validation = docs (source unique) | Les schemas et la validation peuvent diverger |
Source unique de verite
Avec FastAPI, vos modeles Pydantic sont simultanement vos regles de validation et vos schemas de documentation. Avec Flask-RESTX, vous definissez les modeles API separement de votre logique de validation, ce qui peut mener a une derive.
Versionnage de l'API
Au fur et a mesure que votre modele evolue, vous devez versionner votre API pour que les clients existants continuent de fonctionner pendant que les nouveaux clients utilisent la derniere version.
Strategies de versionnage
| Strategie | Exemple | Avantages | Inconvenients |
|---|---|---|---|
| Chemin URL | /api/v1/predict | Clair, facile a router | L'URL change a chaque version |
| Parametre de requete | /predict?version=1 | L'URL reste la meme | Facile a oublier |
| En-tete | Accept: application/vnd.api.v1+json | URLs propres | Moins decouvrable |
| Sous-domaine | v1.api.example.com | Separation propre | Complexite DNS/infra |
Versionnage par chemin URL (recommande)
from fastapi import APIRouter
v1_router = APIRouter(prefix="/api/v1", tags=["v1"])
v2_router = APIRouter(prefix="/api/v2", tags=["v2"])
@v1_router.post("/predict")
def predict_v1(data: PredictionInputV1):
"""Uses model v1 — original feature set."""
result = ml_service_v1.predict(data.model_dump())
return result
@v2_router.post("/predict")
def predict_v2(data: PredictionInputV2):
"""Uses model v2 — expanded feature set with new fields."""
result = ml_service_v2.predict(data.model_dump())
return result
app.include_router(v1_router)
app.include_router(v2_router)
Generation de SDK clients
L'une des fonctionnalites les plus puissantes d'OpenAPI est la generation automatique de clients. A partir de votre specification OpenAPI, vous pouvez generer des bibliotheques clientes dans n'importe quel langage.
Utilisation de openapi-generator
# Install
npm install @openapitools/openapi-generator-cli -g
# Generate Python client
openapi-generator-cli generate \
-i http://localhost:8000/openapi.json \
-g python \
-o ./generated-client/python
# Generate JavaScript client
openapi-generator-cli generate \
-i http://localhost:8000/openapi.json \
-g javascript \
-o ./generated-client/javascript
# Generate TypeScript client
openapi-generator-cli generate \
-i http://localhost:8000/openapi.json \
-g typescript-axios \
-o ./generated-client/typescript
Voir le flux de generation de documentation
Utilisation du client genere
from prediction_api_client import PredictionApi, PredictionInput
client = PredictionApi(base_url="http://localhost:8000")
result = client.predict(PredictionInput(
age=35,
income=55000,
credit_score=720,
employment_years=8,
loan_amount=25000,
))
print(f"Prediction: {result.prediction}")
print(f"Confidence: {result.probability:.2%}")
Bonnes pratiques pour la documentation API
1. Ecrire pour votre audience
| Audience | Ce dont elle a besoin |
|---|---|
| Developpeurs frontend | URLs des endpoints, exemples requete/reponse, codes d'erreur |
| Data scientists | Descriptions des features d'entree, info version du modele, interpretation des sorties |
| Ingenieurs DevOps | Endpoints de sante, authentification, limites de debit, notes de deploiement |
| Chefs de produit | Capacites de l'API a haut niveau, limitations |
2. Liste de verification de la documentation
- Chaque endpoint a un resume et une description
- Tous les parametres de requete sont documentes avec types et contraintes
- Les schemas de reponse incluent tous les champs avec descriptions
- Les reponses d'erreur sont documentees avec des exemples de payloads
- La methode d'authentification est clairement expliquee
- Les limites de debit sont documentees
- Au moins 2 exemples par endpoint (succes + erreur)
- La version du modele et les descriptions de features sont incluses
- Un changelog est maintenu pour les changements de l'API
- Un guide de demarrage existe pour les nouveaux utilisateurs
3. Garder la documentation synchronisee
La regle d'or
Si votre documentation est generee a partir de votre code (approche FastAPI), elle ne peut jamais etre obsolete. Si elle est ecrite separement, elle sera obsolete un jour ou l'autre.
Resume
| Sujet | Point cle |
|---|---|
| OpenAPI | Standard industriel pour decrire les API REST |
| Swagger UI | Documentation interactive generee a partir de la specification OpenAPI |
| Documentation FastAPI | Auto-generee a partir des modeles Pydantic — zero effort supplementaire |
| Documentation Flask | Necessite l'extension Flask-RESTX — definitions de modeles manuelles |
| Versionnage | Le versionnage par chemin URL (/api/v1/) est le plus simple et le plus courant |
| SDK clients | Generer des clients dans n'importe quel langage a partir de votre specification OpenAPI |
| Bonne pratique | Source unique de verite — code = validation = documentation |
Reference rapide Swagger / OpenAPI
| Outil | URL |
|---|---|
| Swagger UI FastAPI | http://localhost:8000/docs |
| ReDoc FastAPI | http://localhost:8000/redoc |
| JSON OpenAPI FastAPI | http://localhost:8000/openapi.json |
| Swagger Flask-RESTX | http://localhost:5000/docs |
| OpenAPI Generator | https://openapi-generator.tech/ |
| Swagger Editor | https://editor.swagger.io/ |
| Specification OpenAPI | https://spec.openapis.org/oas/latest.html |