Wie generiert FastAPI automatische Dokumentation?

Question

Accepted Answer

FastAPI **generiert automatisch interaktive API-Dokumentation** aus deinem Code — deine Routen, Parameter und Pydantic-Modelle werden in ein OpenAPI-Schema umgewandelt, das zwei browsbare Dokumentations-UIs (Swagger UI und ReDoc) ohne zusätzliche Anstrengung bereitstellt.

## Du bekommst Dokumentation kostenlos

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

Allein durch das Schreiben von typisierten Endpoints und Modellen erstellt FastAPI vollständige Dokumentation — keine separaten Dokumentationsdateien zum Schreiben oder Warten erforderlich.

## Die zwei integrierten Dokumentations-UIs

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

Besuche `/docs` und du kannst jeden Endpoint erkunden, erforderliche Parameter und Response-Struktur sehen sowie **echte Anfragen** direkt vom Browser aus **senden** — unverzichtbar während der Entwicklung und für API-Konsumenten.

## Woher der Dokumentationsinhalt kommt

```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 wird aus dem Code abgeleitet, den du bereits schreibst — die Dokumentation bleibt automatisch **synchron** mit der Implementierung.

## Bereichern der Dokumentation

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

## Warum es wichtig ist

Automatische interaktive Dokumentation ist eines der am meisten gefeierten Features von FastAPI und ein Hauptgrund für seine Popularität.

Weil die Dokumentation direkt aus deinem Code generiert wird (Routen, Typhinweise, Pydantic-Modelle, Docstrings), ist sie immer **synchron** mit der tatsächlichen Implementierung — was das chronische Problem eliminiert, dass die Dokumentation veraltet, das handgeschriebene Dokumentation heimsucht.

Die interaktive Swagger UI (`/docs`) ermöglicht es Entwicklern und API-Konsumenten, **Endpoints live im Browser zu erkunden und zu testen**, was die Entwicklererfahrung dramatisch verbessert und Integrationshürden abbaut.

Das generierte OpenAPI-Schema kann auch die Generierung von Client-SDKs und Contract-Testing vorantreiben.

Professionelle, genaue, interaktive API-Dokumentation im Wesentlichen kostenlos zu erhalten — nur durch das Schreiben gut typisierten Code — ist ein erheblicher Produktivitäts- und Qualitätsgewinn, was dies zu einer wichtigen, charakteristischen FastAPI-Funktion macht.