Kaip FastAPI generuoja automatinę dokumentaciją?

Question

Accepted Answer

FastAPI **automatiškai generuoja interaktyvią API dokumentaciją** iš jūsų kodo — jūsų maršrutai, parametrai ir Pydantic modeliai paverčiami OpenAPI schema, kuri suteikia dvi naršomas dokumentacijos UI (Swagger UI ir ReDoc) be papildomų pastangų.

## Jūs nemokamai gaute dokumentaciją

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

Tiesiog parašydami tipizuotus galinimo taškus ir modelius, FastAPI sukuria pilną dokumentaciją — nereikia rašyti ar prižiūrėti atskiro dokumentacijos failo.

## Du įtaisyti dokumentacijos 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.)
```

Apskleidus `/docs` ir galite tyrinėti kiekvieną galiniu taško, pamatyti reikalingus parametrus ir atsakymo formas, bei **siųsti tikrus užklausas** iš naršyklės tiesiogiai — nepakeičiama kūrimo metu ir API vartotojams.

## Kur atsiranda dokumentacijos turinis

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

Viska kilo iš kodo, kurį jau parašėte — dokumentacija išlieka automatiškai **sinchronizuota** su dieginimu.

## Dokumentacijos praturtinimas

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

## Kodėl tai svarbu

Automatinė interaktyvi dokumentacija yra viena iš labiausiai giriamų FastAPI funkcijų ir pagrindinė jo populiarumo priežastis.

Dėl to, kad dokumentacija generuojama tiesiogiai iš jūsų kodo (maršrutai, tipo raiškos, Pydantic modeliai, docstring), ji visada **sinchronizuota** su faktine dieginimu — pašalindama kronišką dokumentacijos pasenimo problemą, kuri kankina rankiniu būdu parašytą dokumentaciją.

Interaktyvi Swagger UI (`/docs`) leidžia kūrėjams ir API vartotojams tyrinėti ir **iš gyvos jėgos bandyti galinių taškų naršyklėje**, drastiškai pagerinant kūrėjo patirtį ir sumažinant integracijos trintį.

Generated OpenAPI schema taip pat gali vadinti kliento SDK generavimą ir sutarčių testavimą.

Gauti profesionalią, tikslią, interaktyvią API dokumentaciją iš esmės nemokamai — tik rašydami gerai tipiziuotą kodą — yra reikšminga produktyvumo ir kokybės laimėjimas, todėl tai yra svarbi, charakteringa FastAPI galimybė.