Hogyan generál a FastAPI automatikus dokumentációt?

Question

Accepted Answer

A FastAPI **automatikusan generál interaktív API dokumentációt az Ön kódjából** — az Ön útvonalai, paraméterei és Pydantic modelljei egy OpenAPI sémába kerülnek, amely két böngészhető doc felhasználói felületet (Swagger UI és ReDoc) működtet nulla dodatási erőfeszítés nélkül.

## Ingyen kapja meg a dokumentációt

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

Csupán a begépelt végpontok és modellek írásával a FastAPI teljes dokumentációt produkál — nincs külön dokumentációs fájl, amelyet írnia vagy karbantartania kellene.

## A két beépített doc felhasználói felület

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

Látogassa meg a `/docs` oldalt, és felderítheti az egyes végpontokat, megismerheti a szükséges paramétereket és a válaszok formáját, valamint **valódi kéréseket küldhet** közvetlenül a böngészőből — felbecsülhetetlen a fejlesztés során és az API felhasználói számára.

## Honnan származik a dokumentáció tartalma

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

Minden az már általa írt kódból származik — a dokumentáció automatikusan **szinkronban marad** a megvalósítással.

## A dokumentáció gazdagítása

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

## Miért fontos

Az automatikus interaktív dokumentáció a FastAPI egyik legünnepeltebb funkciója, és a népszerűségének fő oka.

Mivel a dokumentáció közvetlenül az Ön kódjából (útvonalak, típusos mutató, Pydantic modellek, docstringsek) kerül generálásra, az mindig **szinkronban van** a tényleges megvalósítással — kiküszöbölve azt az idősítési problémát, hogy a dokumentáció elavulttá válik, amely a kézzel írt dokumentációt gyötri.

Az interaktív Swagger UI (`/docs`) lehetővé teszi a fejlesztőknek és az API fogyasztóinak, hogy **élő végpontokat fedezzenek fel és teszteljenek a böngészőben**, ami drámaian javítja a fejlesztői tapasztalatot és csökkenti az integrációs súrlódást.

A generált OpenAPI séma támogathatja az ügyféloldali SDK generálást és a szerződés tesztelést is.

A professzionális, pontos, interaktív API dokumentáció lényegében ingyenesen történő beszerzése — csupán a jól begépelt kód írásával — jelentős termelékenységi és minőségi nyereség, ami a FastAPI fontos, jellegzetes képességévé teszi ezt.