Jak FastAPI generuje automatyczną dokumentację?

Question

Accepted Answer

FastAPI **automatycznie generuje interaktywną dokumentację API** z Twojego kodu — Twoje trasy, parametry i modele Pydantic są zamieniane na schemat OpenAPI, który zasilany dwiema przeglądarkami interfejsów dokumentacji (Swagger UI i ReDoc) bez żadnego dodatkowego wysiłku.

## Dokumentacja za darmo

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

Just by writing typed endpoints and models, FastAPI produces complete docs — no separate documentation file to write or maintain.

## Dwa wbudowane interfejsy dokumentacji

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

Odwiedź `/docs` i możesz eksplorować każdy endpoint, zobaczić wymagane parametry i kształt odpowiedzi, oraz **wysyłać rzeczywiste żądania** bezpośrednio z przeglądarki — nieocenione podczas rozwoju i dla konsumentów API.

## Skąd pochodzi zawartość dokumentacji

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

Wszystko jest pochodzi z kodu, który już piszesz — dokumentacja pozostaje automatycznie **zsynchronizowana** z implementacją.

## Wzbogacanie dokumentacji

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

## Dlaczego to ważne

Automatyczna dokumentacja interaktywna to jedna z najbardziej znanych cech FastAPI i główny powód jego popularności.

Ponieważ dokumentacja jest generowana bezpośrednio z Twojego kodu (trasy, adnotacje typów, modele Pydantic, docstringi), zawsze są **zsynchronizowane** z rzeczywistą implementacją — eliminując chroniczny problem dokumentacji ulegającej dezaktualizacji, który nęka dokumenty pisane ręcznie.

Interaktywny Swagger UI (`/docs`) pozwala deweloperom i konsumentom API eksplorować i **testować endpointy na żywo w przeglądarce**, dramatycznie poprawiając doświadczenie dewelopera i zmniejszając tarcie integracji.

Wygenerowany schemat OpenAPI może również napędzać generowanie SDK klienta i testowanie kontraktu.

Uzyskanie profesjonalnej, dokładnej, interaktywnej dokumentacji API zasadniczo za darmo — po prostu pisząc dobrze typizowany kod — to znaczący zysk produktywności i jakości, czyniąc to ważną, charakterystyczną możliwością FastAPI.