Come genera FastAPI la documentazione automatica?

Question

Accepted Answer

FastAPI **genera automaticamente documentazione API interattiva** dal tuo codice — le tue rotte, parametri e modelli Pydantic vengono trasformati in uno schema OpenAPI, che alimenta due UI di documentazione esplorabile (Swagger UI e ReDoc) senza alcuno sforzo aggiuntivo.

## Ottieni la documentazione gratuitamente

```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
```

Scrivendo semplicemente endpoint e modelli tipizzati, FastAPI produce documentazione completa — nessun file di documentazione separato da scrivere o mantenere.

## Le due UI di documentazione integrate

```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.)
```

Visita `/docs` e puoi esplorare ogni endpoint, vedere i parametri obbligatori e le forme di risposta, e **inviare richieste reali** direttamente dal browser — inestimabile durante lo sviluppo e per i consumatori dell'API.

## Da dove viene il contenuto della documentazione

```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
```

Tutto deriva dal codice che già scrivi — la documentazione rimane automaticamente **in sincronizzazione** con l'implementazione.

## Arricchire la documentazione

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

## Perché è importante

La documentazione interattiva automatica è una delle caratteristiche più celebrate di FastAPI e una ragione principale della sua popolarità.

Poiché la documentazione viene generata direttamente dal tuo codice (rotte, type hint, modelli Pydantic, docstring), è sempre **in sincronizzazione** con l'implementazione effettiva — eliminando il problema cronico della documentazione che diventa obsoleta, che affligge i documenti scritti a mano.

L'interfaccia Swagger UI interattiva (`/docs`) consente agli sviluppatori e ai consumatori dell'API di esplorare e **testare gli endpoint dal vivo nel browser**, migliorando drammaticamente l'esperienza dello sviluppatore e riducendo l'attrito nell'integrazione.

Lo schema OpenAPI generato può anche guidare la generazione di SDK client e il contract testing.

Ottenere documentazione API professionale, accurata e interattiva essenzialmente gratuitamente — scrivendo semplicemente codice ben tipizzato — è un significativo guadagno di produttività e qualità, rendendo questa una capacità importante e distintiva di FastAPI.