Tự động hóa Documentation với AI: Từ Code đến API Docs

Documentation luôn là phần việc khiến tôi… lười nhất mỗi khi kết thúc một sprint. Code xong tính năng đã mệt, giờ lại phải ngồi nhớ lại tham số này làm gì, response kia trả về cái gì để viết vào file Markdown hay Swagger thì thật sự nản.

Nhưng từ khi tích hợp AI vào quy trình làm việc, gánh nặng này đã giảm đi đáng kể. Không phải là AI viết hộ 100%, mà nó đóng vai trò là người soạn thảo bản nháp (draft) cực nhanh, tôi chỉ cần đóng vai trò Editor để duyệt lại. Hôm nay tôi sẽ chia sẻ cách tôi “lười” một cách thông minh với AI trong việc viết docs.

Tại sao Developer ghét viết Docs?

Có ba lý do chính mà tôi và đồng nghiệp thường than phiền:

1. Lệch pha ngữ cảnh (Context Switching): Đang tư duy logic code, phải chuyển sang tư duy ngôn ngữ giải thích rất dễ bị “gãy” mạch.
2. Bảo trì: Code sửa một đường, docs vẫn nằm im một sào. Sau 2 tuần, docs trở thành “rác” vì không còn đúng với code.
3. Tốn thời gian: Viết một bản mô tả API tử tế có khi tốn ngang thời gian code API đó.

AI giải quyết được vấn đề số 1 và 3 rất tốt. Còn vấn đề số 2, nó hỗ trợ cập nhật nhanh hơn.

Quy trình Tự động hóa Documentation

Tôi sử dụng kết hợp GitHub Copilot (hoặc Cursor) và một chút script CI/CD để lo liệu việc này.

1. Docstring ở cấp độ Function/Class

Đây là mức cơ bản nhất. Đừng bao giờ viết docstring thủ công nữa.

Cách làm cũ: Gõ /** rồi enter, sau đó tự điền @param, @return.

Cách làm với AI: Tôi chỉ cần bôi đen hàm, nhấn Cmd+K (trong Cursor/VS Code) và gõ: “Add detailed docblock explanation for this function, focus on edge cases”.

Ví dụ code gốc:

public function calculateDiscount($user, $cartTotal) {
    if ($user->isVip()) {
        return $cartTotal * 0.9;
    }
    return $cartTotal > 1000 ? $cartTotal * 0.95 : $cartTotal;
}

AI sẽ sinh ra:

/**
 * Tính toán mức giảm giá dựa trên hạng thành viên và tổng giỏ hàng.
 *
 * Logic áp dụng:
 * 1. Khách hàng VIP: Giảm 10% trên toàn bộ đơn hàng (ưu tiên cao nhất).
 * 2. Khách thường:
 *    - Đơn > 1000: Giảm 5%.
 *    - Đơn <= 1000: Không giảm.
 *
 * @param User $user Đối tượng khách hàng.
 * @param float $cartTotal Tổng giá trị đơn hàng trước thuế.
 * @return float Giá trị đơn hàng sau khi giảm giá.
 */
public function calculateDiscount($user, $cartTotal) { ... }

Nó không chỉ liệt kê tham số, mà còn giải thích logic (VIP ưu tiên cao nhất) - điều mà tools tạo doc tự động ngày xưa không làm được.

2. Tạo API Documentation (OpenAPI/Swagger)

Đây mới là phần “ngon” nhất. Thay vì ngồi viết file YAML dài ngoằng, tôi dùng AI để generate nó từ Controller.

Ví dụ tôi có một Controller trong Laravel:

class OrderController extends Controller {
    public function store(StoreOrderRequest $request) {
        $order = Order::create($request->validated());
        return response()->json($order, 201);
    }
}

Tôi prompt cho AI: “Generate OpenAPI 3.0 path definition for this store method in YAML format. Use StoreOrderRequest rules to define request body schema.”

AI sẽ đọc cả file StoreOrderRequest để biết field nào required, field nào là email, min/max bao nhiêu và sinh ra bản YAML gần như hoàn chỉnh. Việc của tôi chỉ là copy nó vào file swagger.yaml.

3. Viết README.md cho Repository

Một repo mà không có README thì coi như vứt đi. Nhưng viết README cũng rất ngại.

Tôi thường dùng prompt sau cho Chatbot (Claude/GTP) bằng cách ném toàn bộ cấu trúc thư mục và vài file chính vào context:

“Tôi vừa viết xong một thư viện xử lý ảnh bằng Laravel. Hãy đóng vai một Senior Technical Writer, viết file README.md chuyên nghiệp gồm các mục: Introduction, Installation, Usage (kèm code example), và Contribution. Giọng văn ngắn gọn, dễ hiểu.”

Kết quả nhận được thường đạt 80-90% yêu cầu. Tôi chỉ cần sửa lại các câu lệnh cài đặt cho chính xác version là xong.

Những cái bẫy cần tránh (Warning)

Dù AI giỏi, nhưng đừng tin nó tuyệt đối.

• Business Logic sai: AI nhìn code đoán logic, đôi khi code mình viết rắc rối quá nó đoán sai. Luôn phải đọc lại phần “Logic áp dụng”.
• Leak dữ liệu: Cẩn thận khi paste code chứa API Key hay thông tin nhạy cảm vào khung chat của các AI public.
• Văn phong “Robot”: Đôi khi AI dùng từ ngữ quá trang trọng hoặc sáo rỗng. Hãy sửa lại cho giống “người” hơn.

Kết luận

Documentation là tài sản của dự án, không phải gánh nặng. Bằng cách dùng AI, tôi đã chuyển đổi việc viết docs từ “trách nhiệm phải làm” sang “quy trình tự động nhẹ nhàng”. Hãy bắt đầu từ việc nhỏ nhất là auto-generate docblock cho mỗi commit, bạn sẽ thấy code base của mình sáng sủa hơn hẳn sau một tháng.