FastAPI sinh tài liệu tự động như thế nào?

Question

Accepted Answer

FastAPI **tự động sinh tài liệu API tương tác** từ code của bạn — các route, tham số và Pydantic model được chuyển thành một OpenAPI schema, schema này cấp nguồn cho hai giao diện tài liệu duyệt được (Swagger UI và ReDoc) mà không tốn công thêm.

## Bạn nhận tài liệu miễn phí

```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 → mô tả endpoint
    return item
```

Chỉ bằng việc viết các endpoint và model có kiểu, FastAPI tạo ra tài liệu đầy đủ — không có file tài liệu riêng nào để viết hay bảo trì.

## Hai giao diện tài liệu tích hợp sẵn

```text
/docs   → Swagger UI — tương tác: duyệt các endpoint VÀ test chúng trong trình duyệt
          (điền tham số, gửi request, xem response trực tiếp)
/redoc  → ReDoc — một góc nhìn kiểu tham khảo sạch sẽ, dễ đọc
/openapi.json → OpenAPI schema thô (dùng được để sinh client SDK, v.v.)
```

Truy cập `/docs` và bạn có thể khám phá mọi endpoint, xem các tham số bắt buộc và hình dạng response, và **gửi request thật** trực tiếp từ trình duyệt — vô giá trong lúc phát triển và cho người tiêu thụ API.

## Nội dung tài liệu đến từ đâu

```text
Route decorator → path, HTTP method, tag, summary
Type hint       → kiểu tham số, bắt buộc/tùy chọn
Pydantic model  → schema request/response, ràng buộc & mô tả field
Docstring       → mô tả endpoint
Field(..., description=, example=) → tài liệu và ví dụ cấp field
```

Mọi thứ được suy ra từ code bạn đã viết — tài liệu tự động luôn **đồng bộ** với phần triển khai.

## Làm phong phú tài liệu

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

## Tại sao điều này quan trọng

Tài liệu tương tác tự động là một trong những tính năng được ca ngợi nhất của FastAPI và là lý do lớn cho sự phổ biến của nó.

Vì tài liệu được sinh trực tiếp từ code của bạn (route, type hint, Pydantic model, docstring), chúng luôn **đồng bộ** với phần triển khai thực tế — loại bỏ vấn đề kinh niên là tài liệu lỗi thời dần, vốn ám ảnh tài liệu viết tay.

Swagger UI tương tác (`/docs`) cho phép lập trình viên và người tiêu thụ API khám phá và **test endpoint trực tiếp trong trình duyệt**, cải thiện đáng kể trải nghiệm phát triển và giảm ma sát tích hợp.

OpenAPI schema được sinh ra cũng có thể điều khiển việc sinh client SDK và contract testing.

Nhận được tài liệu API chuyên nghiệp, chính xác, tương tác gần như miễn phí — chỉ bằng việc viết code có kiểu tốt — là một chiến thắng lớn về năng suất và chất lượng, biến đây thành một khả năng FastAPI quan trọng và đặc trưng.