Jak FastAPI generuje automatickou dokumentaci?

Question

Accepted Answer

FastAPI **automaticky generuje interaktivní API dokumentaci** z vašeho kódu — vaše trasy, parametry a Pydantic modely se převádějí do schématu OpenAPI, které pohání dvě prohlížitelné dokumentační UI (Swagger UI a ReDoc) bez dodatečného úsilí.

## Dokumentaci získáte zdarma

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

Pouhým zapsáním typizovaných endpointů a modelů FastAPI vytváří úplnou dokumentaci — není potřeba psát nebo udržovat žádný samostatný dokumentační soubor.

## Dvě vestavěné dokumentační UI

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

Návštěvou `/docs` můžete prozkoumat každý endpoint, zobrazit požadované parametry a tvary odpovědí a **odeslat skutečné požadavky** přímo z prohlížeče — neocenitelné při vývoji a pro uživatele API.

## Odkud pochází obsah dokumentace

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

Všechno je odvozeno z kódu, který už píšete — dokumentace zůstává automaticky **synchronizovaná** s implementací.

## Obohacování dokumentace

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

## Proč je to důležité

Automatická interaktivní dokumentace je jednou z nejceňovanějších funkcí FastAPI a hlavním důvodem její popularity.

Protože je dokumentace generována přímo z vašeho kódu (trasy, typové nápovědy, Pydantic modely, docstrings), je vždy **synchronizovaná** se skutečnou implementací — čímž se eliminuje chronický problém dokumentace zaostávající za realitou, který sužuje ručně psanou dokumentaci.

Interaktivní Swagger UI (`/docs`) umožňuje vývojářům a uživatelům API **prozkoumat a testovat endpointy živě v prohlížeči**, což dramaticky zlepšuje vývojářské zkušenosti a snižuje integrační tření.

Vygenerované schéma OpenAPI může také řídit generování SDK klienta a testování kontraktů.

Získání profesionální, přesné, interaktivní API dokumentace v podstatě zdarma — jen psaním dobře typizovaného kódu — je významný přínos v produktivitě a kvalitě, čímž se jedná o důležitou a charakteristickou schopnost FastAPI.