Hoe genereert FastAPI automatische documentatie?

Question

Accepted Answer

FastAPI **genereert automatisch interactieve API-documentatie** uit je code — je routes, parameters en Pydantic-modellen worden omgezet in een OpenAPI-schema, dat twee browsable doc UI's (Swagger UI en ReDoc) aandrijft zonder extra inspanning.

## Je krijgt documentatie gratis

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

Door alleen getypte endpoints en modellen te schrijven, produceert FastAPI volledige documentatie — geen apart documentatiebestand om te schrijven of onderhouden.

## De twee ingebouwde doc UI's

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

Bezoek `/docs` en je kunt elk endpoint verkennen, vereiste parameters en antwoordvormen zien, en **echte verzoeken rechtstreeks vanuit de browser versturen** — onschatbaar tijdens ontwikkeling en voor API-consumenten.

## Waar de documentatie-inhoud vandaan komt

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

Alles is afgeleid van de code die je al schrijft — de documentatie blijft automatisch **synchroon** met de implementatie.

## De documentatie verrijken

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

## Waarom het belangrijk is

Automatische interactieve documentatie is een van de meest geprezen functies van FastAPI en een belangrijke reden voor de populariteit ervan.

Omdat de documentatie rechtstreeks uit je code wordt gegenereerd (routes, type hints, Pydantic-modellen, docstrings), is deze altijd **synchroon** met de daadwerkelijke implementatie — het chronische probleem van documentatie die verouderd raakt, dat handgeschreven documentatie plaagt, wordt geëlimineerd.

De interactieve Swagger UI (`/docs`) stelt ontwikkelaars en API-consumenten in staat om endpoints **live in de browser te verkennen en te testen**, wat de developer experience dramatisch verbetert en integratiewrijving vermindert.

Het gegenereerde OpenAPI-schema kan ook client SDK-generatie en contract-testing aandrijven.

Professionele, nauwkeurige, interactieve API-documentatie in feite gratis krijgen — alleen door goed getypte code te schrijven — is een aanzienlijke productiviteits- en kwaliteitswins, wat dit een belangrijke en onderscheidende FastAPI-mogelijkheid maakt.