Apidog là một nền tảng quản lý và cộng tác API hỗ trợ nhập các đặc tả API dưới nhiều định dạng. Nó có thể trực tiếp nhập hầu hết các định dạng đặc tả API phổ biến, bao gồm OpenAPI/Swagger, Postman Collections, các tệp HAR và lệnh cURL.
Tuy nhiên, trong nhiều dự án thực tế, thách thức chính không phải là cách nhập các đặc tả API — mà là không có sẵn đặc tả API nào để nhập ngay từ đầu. Một số hệ thống cũ hoặc hệ thống kế thừa chưa bao giờ duy trì tài liệu API và không có tệp OpenAPI hoặc Swagger.
Trong những trường hợp này, nếu bạn cần nhanh chóng xây dựng lại tài liệu API bị thiếu hoặc tạo các trường hợp kiểm thử để người kiểm thử có thể làm việc với dữ liệu thực, việc sử dụng công cụ bắt gói tin thường là cách tiếp cận nhanh nhất.
Bằng cách bắt giữ lưu lượng HTTP/HTTPS của ứng dụng, lọc các yêu cầu hữu ích, xuất chúng dưới dạng HAR hoặc cURL, và sau đó nhập chúng vào Apidog, bạn có thể nhanh chóng tạo tài liệu API và đặt nền móng cho việc kiểm thử API tiếp theo.
Có nhiều công cụ có sẵn để ghi lại lưu lượng mạng. Bài viết này sử dụng Charles Proxy làm ví dụ để minh họa các thao tác cụ thể liên quan, nhưng bạn cũng có thể sử dụng các lựa chọn thay thế như Proxyman, Fiddler, hoặc các công cụ dành cho nhà phát triển tích hợp trong trình duyệt của bạn để bắt gói tin. Quy trình làm việc cốt lõi về cơ bản là giống nhau giữa các công cụ này.
Cài đặt và Cấu hình Cơ bản Charles
Charles cung cấp bản dùng thử miễn phí 30 ngày. Bạn có thể tải xuống phiên bản mới nhất từ trang web chính thức và cài đặt nó trên hệ thống của mình.
Khi bạn khởi chạy Charles lần đầu tiên, nó có thể hỏi bạn có muốn tự động cấu hình cài đặt Mạng hay không. Nên chọn "Grant Privileges" (Cấp quyền) để cấp các quyền cần thiết. Điều này cho phép Charles tự động bắt giữ lưu lượng HTTP từ hệ thống của bạn.
Cài đặt Chứng chỉ Gốc của Charles để Bắt giữ HTTPS
Để bắt giữ lưu lượng HTTPS, bạn cần cài đặt chứng chỉ gốc của Charles. Bước này rất cần thiết vì hầu hết các API hiện đại đều sử dụng HTTPS.
Trên macOS:
- Nhấp vào "Help → SSL Proxying → Install Charles Root Certificate" (Trợ giúp → Proxy SSL → Cài đặt Chứng chỉ Gốc Charles) từ thanh menu
- Ứng dụng Truy cập Chuỗi khóa sẽ tự động mở
- Tìm kiếm và định vị chứng chỉ Charles Proxy
- Nhấp đúp vào đó và thay đổi cài đặt tin cậy thành "Always Trust" (Luôn tin cậy)
Trên Windows:
- Nhấp vào "Help → SSL Proxying → Install Charles Root Certificate" (Trợ giúp → Proxy SSL → Cài đặt Chứng chỉ Gốc Charles) từ thanh menu
- Trong quá trình cài đặt, hãy cài đặt chứng chỉ vào kho "Trusted Root Certification Authorities" (Cơ quan cấp chứng chỉ gốc đáng tin cậy)
Bật Proxy SSL
Sau khi chứng chỉ được cài đặt, bạn cần bật proxy SSL:
- Chọn Proxy → SSL Proxying Settings (Cài đặt Proxy SSL) từ thanh menu của Charles
- Đánh dấu tùy chọn "Enable SSL Proxying" (Bật Proxy SSL)
3. Thêm các tên miền (Host) và cổng (Port 443) bạn muốn bắt giữ vào danh sách
4. Bạn cũng có thể sử dụng * để giám sát tất cả các tên miền
Sau khi cấu hình hoàn tất, Charles có thể bắt giữ toàn bộ các yêu cầu và phản hồi HTTP/HTTPS.
Mẹo: Nếu bạn không chắc ứng dụng của mình sử dụng tên miền nào, bạn có thể vận hành ứng dụng một cách tự do trước, sau đó quan sát các yêu cầu trong mục "Encrypted" (Đã mã hóa) trong danh sách phiên của Charles. Ghi lại các tên miền tương ứng và sau đó thêm chúng vào cài đặt SSL Proxying của Charles.
Ghi lại Lưu lượng API từ Ứng dụng của Bạn
Khởi chạy ứng dụng hoặc trang web bạn muốn phân tích và tương tác với các tính năng khác nhau, chẳng hạn như đăng nhập, truy vấn dữ liệu, gửi biểu mẫu hoặc tải tệp lên. Cây phiên ở phía bên trái của Charles sẽ cập nhật theo thời gian thực, nhóm các yêu cầu theo tên miền và URL.
Khi bạn chọn một yêu cầu cụ thể, bảng điều khiển bên phải sẽ hiển thị thông tin cơ bản và nội dung phản hồi của yêu cầu đó. Trong tab Contents (Nội dung), JSON và các phản hồi khác được thu gọn thành cấu trúc cây, giúp dễ dàng nhanh chóng hiểu cấu trúc dữ liệu và các trường.
Lọc và Xuất các Endpoint API
Sau khi ghi lại hoàn tất, bạn có thể thấy rằng một số lượng lớn các yêu cầu đã được bắt giữ. Ngoài các lời gọi API thực tế, còn có nhiều yêu cầu tài nguyên tĩnh, lời gọi dịch vụ của bên thứ ba và lưu lượng mạng khác. Lúc này, bạn cần lọc và chỉ giữ lại các endpoint mà bạn quan tâm.
Tùy chọn lọc
1. Tập trung vào các tên miền hoặc đường dẫn cụ thể:
Nhấp chuột phải vào một tên miền hoặc đường dẫn và chọn "Focus" (Tập trung)
Charles sẽ chỉ giữ lại các yêu cầu dưới nút đó, thuận tiện cho việc phân tích của bạn
2. Xóa các yêu cầu không liên quan:
Nhấp chuột phải vào các yêu cầu không liên quan và chọn "Clear" (Xóa) để loại bỏ chúng
Hoặc chọn nhiều yêu cầu và xóa chúng hàng loạt
3. Xử lý các vấn đề về bộ nhớ đệm:
Nếu bộ nhớ đệm gây ra lỗi hiển thị HTML hoặc JSON, hãy nhấp chuột phải và chọn "No Caching" (Không lưu bộ nhớ đệm)
Điều này khiến Charles bỏ qua bộ nhớ đệm trong các yêu cầu tiếp theo, cho phép bạn bắt giữ nội dung phản hồi đầy đủ
Xuất dưới dạng File HAR
Sau khi lọc hoàn tất, hãy xuất các phiên đã chọn của bạn:
- Chọn các phiên bạn muốn xuất:
Bạn có thể chọn toàn bộ một nút tên miền, hoặc
Giữ Cmd (Mac) hoặc Ctrl (Windows) và chọn từng yêu cầu cụ thể
Chọn File → Export Session (Tệp → Xuất phiên) từ thanh menu
Trong hộp thoại xuất, chọn xuất theo định dạng "HTTP Archive (.har)" để tạo tệp HAR
Nhập vào Apidog để Tự động Tạo Tài liệu API
Bây giờ là lúc nhập lưu lượng mạng đã bắt giữ của bạn vào Apidog:
- Mở ứng dụng Apidog
2. Đi tới Project Settings → Import Data → .har File (Cài đặt Dự án → Nhập Dữ liệu → Tệp .har)
3. Chọn tệp HAR bạn đã xuất từ Charles
Apidog sẽ tự động phân tích nội dung tệp và hiển thị thông tin endpoint được phát hiện trong khu vực xem trước, bao gồm:
- Số lượng endpoint được phát hiện
- Phương thức yêu cầu (GET, POST, PUT, DELETE, v.v.)
Trong quá trình nhập, bạn có thể cấu hình các tùy chọn như:
- Mô-đun nào để nhập vào
- Có ghi đè các endpoint hiện có hay không
Sau khi nhập hoàn tất, bạn có thể xem các endpoint trong mô-đun tương ứng.
Tinh chỉnh và Tối ưu hóa Tài liệu API
Tài liệu API được tự động tạo là một điểm khởi đầu tuyệt vời, nhưng thường yêu cầu điều chỉnh thêm để đáp ứng các yêu cầu kinh doanh của bạn. Dưới đây là một số cải tiến phổ biến:
- Cải thiện tên endpoint: Thay đổi tên chung chung thành những tên mô tả hơn
- Thêm mô tả tham số: Ghi lại chức năng của từng tham số và khi nào nên sử dụng chúng
- Tinh chỉnh các thành phần phản hồi: Sắp xếp các thành phần phản hồi để phù hợp với logic nghiệp vụ của bạn
- Thêm ví dụ: Bao gồm các yêu cầu và phản hồi mẫu
- Cấu hình xác thực: Nếu một endpoint yêu cầu xác thực, hãy cấu hình thông tin tương ứng trong biến môi trường hoặc cài đặt Xác thực của Apidog. Điều này đảm bảo rằng các lời gọi API của bạn hoạt động chính xác khi kiểm thử.
Lời kết
Bằng cách ghi lại lưu lượng HTTP/HTTPS bằng các công cụ bắt gói tin và sau đó nhập vào Apidog, bạn có thể nhanh chóng tạo tài liệu API và cung cấp dữ liệu thực để hỗ trợ kiểm thử.
Cho dù đó là trình duyệt, ứng dụng máy tính để bàn hay ứng dụng di động, phương pháp này có thể giảm đáng kể thời gian chuẩn bị tài liệu API và cho phép nhóm của bạn nhanh chóng bắt đầu với việc kiểm thử và phát triển API.