Comment FastAPI génère-t-il la documentation automatique ?

Question

Accepted Answer

FastAPI **génère automatiquement une documentation API interactive** à partir de votre code — vos routes, paramètres et modèles Pydantic sont transformés en schéma OpenAPI, qui alimente deux interfaces de documentation consultables (Swagger UI et ReDoc) sans effort supplémentaire.

## Vous obtenez la documentation gratuitement

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

En écrivant simplement des endpoints typés et des modèles, FastAPI produit une documentation complète — aucun fichier de documentation séparé à écrire ou maintenir.

## Les deux interfaces de documentation intégrées

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

Visitez `/docs` et vous pouvez explorer chaque endpoint, voir les paramètres requis et les structures de réponse, et **envoyer des requêtes réelles** directement depuis le navigateur — essentiel pendant le développement et pour les utilisateurs de l'API.

## D'où provient le contenu de la documentation

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

Tout est dérivé du code que vous écrivez déjà — la documentation reste automatiquement **synchronisée** avec l'implémentation.

## Enrichir la documentation

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## Pourquoi c'est important

La documentation interactive automatique est l'une des fonctionnalités les plus célébrées de FastAPI et une raison majeure de sa popularité.

Parce que la documentation est générée directement à partir de votre code (routes, annotations de type, modèles Pydantic, docstrings), elle reste toujours **synchronisée** avec l'implémentation réelle — éliminant le problème chronique de la documentation devenant obsolète, qui afflige les docs écrites manuellement.

L'interface Swagger UI interactive (`/docs`) permet aux développeurs et aux utilisateurs de l'API d'explorer et de **tester les endpoints en direct dans le navigateur**, améliorant considérablement l'expérience développeur et réduisant les frictions d'intégration.

Le schéma OpenAPI généré peut également permettre la génération de SDK clients et les tests de contrat.

Obtenir une documentation API professionnelle, précise et interactive essentiellement gratuitement — en écrivant simplement du code bien typé — est un gain significatif de productivité et de qualité, ce qui en fait une capacité importante et distinctive de FastAPI.