Bagaimanakah FastAPI menjana dokumentasi automatik?

Question

Accepted Answer

FastAPI **secara otomatis menghasilkan dokumentasi API interaktif** dari kod anda — laluan, parameter, dan model Pydantic anda diubah menjadi skema OpenAPI, yang menjalankan dua UI dokumentasi yang boleh dijelajahi (Swagger UI dan ReDoc) tanpa sebarang usaha tambahan.

## Anda mendapatkan dokumentasi secara percuma

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

Hanya dengan menulis titik akhir dan model yang ditaip, FastAPI menghasilkan dokumentasi lengkap — tiada fail dokumentasi berasingan untuk ditulis atau diselenggarakan.

## Dua UI dokumentasi terbina dalam

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

Kunjungi `/docs` dan anda boleh menjelajahi setiap titik akhir, melihat parameter yang diperlukan dan bentuk respons, dan **menghantar permintaan sebenar** terus dari penyemak imbas — amat berharga semasa pembangunan dan untuk pengguna API.

## Tempat asal kandungan dokumentasi

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

Semuanya berasal dari kod yang telah anda tulis — dokumentasi tetap secara otomatis **tersinkron** dengan pelaksanaan.

## Memperkaya dokumentasi

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

## Mengapa ia penting

Dokumentasi interaktif otomatis adalah salah satu ciri FastAPI yang paling dipuji dan alasan utama kepopulerannya.

Kerana dokumentasi dijana terus dari kod anda (laluan, petunjuk jenis, model Pydantic, docstring), ia sentiasa **tersinkron** dengan pelaksanaan sebenar — menghapuskan masalah kronik dokumentasi yang ketinggalan zaman, yang melanda dokumen yang ditulis tangan.

UI Swagger interaktif (`/docs`) membenarkan pembangun dan pengguna API menjelajahi dan **menguji titik akhir langsung dalam penyemak imbas**, meningkatkan pengalaman pembangun secara drastik dan mengurangkan geseran integrasi.

Skema OpenAPI yang dijana juga boleh mendorong pembuatan SDK klien dan ujian kontrak.

Mendapatkan dokumentasi API profesional, tepat, dan interaktif pada asasnya secara percuma — hanya dengan menulis kod yang ditaip dengan baik — adalah kemenangan produktiviti dan kualiti yang ketara, menjadikan ini keupayaan penting dan tersendiri FastAPI.