Kako FastAPI automatski genira dokumentaciju?

Question

Accepted Answer

FastAPI **automatski genira interaktivnu API dokumentaciju iz vašeg koda** — vaše rute, parametri i Pydantic modeli se pretvaraju u OpenAPI shemu, koja napaja dva pregledna doc UI-ja (Swagger UI i ReDoc) bez dodatnog napora.

## Dobivate dokumentaciju besplatno

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

Samo pisanjem tipiziranih endpoint-ova i modela, FastAPI proizvodi cjelovitu dokumentaciju — nema zasebne datoteke dokumentacije koju trebate napisati ili održavati.

## Dva ugrađena doc UI-ja

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

Poločite `/docs` i možete istražiti svaki endpoint, vidjeti potrebne parametre i oblike odgovora, te **slati prave zahtjeve** izravno iz preglednika — neprocjenjivo tijekom razvoja i za korisnike API-ja.

## Odakle dolazi sadržaj dokumentacije

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

Sve je izvedeno iz koda koji već napišete — dokumentacija ostaje automatski **u sinkronizaciji** s implementacijom.

## Obogaćivanje dokumentacije

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

## Zašto je to važno

Automatska interaktivna dokumentacija je jedna od najhvaljivanijih značajki FastAPI-ja i glavni je razlog njegovog populariteta.

Jer se dokumentacija genira izravno iz vašeg koda (rute, type hints, Pydantic modeli, docstrings), ona je uvijek **u sinkronizaciji** s stvarnom implementacijom — što eliminiše kronični problem da dokumentacija zaostaje, što muči ručno napisanu dokumentaciju.

Interaktivni Swagger UI (`/docs`) omogućuje programerima i korisnicima API-ja da **istražuju i testiraju endpoint-ove uživo u pregledniku**, što dramatično poboljšava iskustvo razvoja i smanjuje trenja pri integraciji.

Generirani OpenAPI shema može также pokrenuti generiranje SDK-a za klijente i testiranje ugovora.

Dobivanje profesionalne, točne, interaktivne API dokumentacije u biti besplatno — samo pisanjem dobro tipiziranog koda — je značajna dobit u produktivnosti i kvaliteti, što čini ovo važnom, prepoznatljivom mogućnosti FastAPI-ja.