Trước khi kiểm thử API, tester cần biết cách đọc API documentation. Tài liệu cho biết hệ thống cung cấp endpoint nào, cần gửi dữ liệu gì, yêu cầu xác thực ra sao và có thể nhận lại những response nào.

Trong bài này, chúng ta sử dụng Swagger UI của Elitest RealWorld Playground làm ví dụ và tập trung vào nhóm API article/comment.

Một endpoint trên Swagger gồm những gì?

Mỗi dòng endpoint thường bắt đầu bằng HTTP method và path, ví dụ:

POST /api/articles/{slug}/comments

Khi mở dòng này trên Swagger của Elitest, tester sẽ thấy các khu vực chính: Parameters, Request body, Responses và Schemas. Hãy đọc lần lượt.

Bước 1: Tìm endpoint cần kiểm thử

Bắt đầu từ mục tiêu nghiệp vụ. Ví dụ, yêu cầu là “người dùng đã đăng nhập có thể bình luận vào bài viết”. Trên Swagger, tìm nhóm comments, sau đó chọn endpoint có mô tả Add Comment:

POST /api/articles/{slug}/comments

Đừng chọn endpoint chỉ vì tên gần giống. Cùng resource comment còn có endpoint lấy danh sách comment hoặc xoá comment, nhưng mục tiêu và dữ liệu đầu vào khác nhau.

Bước 2: Xác định HTTP method

Endpoint ví dụ sử dụng method POST, nghĩa là client yêu cầu server tạo một comment mới. Method là một phần của định danh endpoint; cùng một path nhưng method khác có thể thực hiện chức năng hoàn toàn khác.

Bước 3: Parameter nào bắt buộc?

Trong phần Parameters, Swagger cho biết tên parameter, vị trí, kiểu dữ liệu và thuộc tính required. Endpoint thêm comment có path parameter:

Dấu ngoặc nhọn {slug} là placeholder. Khi gọi thật, tester phải thay bằng slug cụ thể:

POST /api/articles/huong-dan-api-testing/comments

Parameter có thể nằm ở path, query, header hoặc cookie. Ví dụ, endpoint GET /api/articles có các query parameter không bắt buộc như tag, author, limit và offset.

GET /api/articles?tag=testing&limit=10&offset=0

Bước 4: Đọc kiểu dữ liệu và constraint

Biết field là string hay integer mới chỉ là bước đầu. Tester cần tìm thêm các constraint như:

• required: có bắt buộc xuất hiện không?
• minLength/maxLength: độ dài chuỗi cho phép.
• minimum/maximum: khoảng giá trị số.
• format: email, date-time, UUID…
• enum: chỉ nhận một số giá trị cố định.
• nullable hoặc schema có null: field có chấp nhận null không?

Trong API Elitest, body của comment là string, bắt buộc, có độ dài từ 1 đến 60.000 ký tự. Với GET /api/articles, limit là integer từ 1 đến 100, mặc định 20; offset là integer từ 0, mặc định 0.

Bước 5: Đọc request body mẫu

Phần Request body cho biết content type và schema dữ liệu gửi lên. Endpoint thêm comment yêu cầu application/json với cấu trúc:

{
  "comment": {
    "body": "Bài viết rất hữu ích!"
  }
}

Cả object comment và field body đều bắt buộc. Schema cũng khai báo additionalProperties: false, tức là cấu trúc không cho phép tự ý thêm field ngoài định nghĩa.

Bước 6: Đọc response schema

Response schema mô tả hình dạng dữ liệu server dự kiến trả về. Khi tạo comment thành công, API Elitest trả object gốc có key comment. Bên trong gồm các field bắt buộc:

• id: integer.
• createdAt: string.
• updatedAt: string.
• body: string.
• author: object chứa thông tin tác giả.

{
  "comment": {
    "id": 123,
    "createdAt": "2026-09-09T06:30:00Z",
    "updatedAt": "2026-09-09T06:30:00Z",
    "body": "Bài viết rất hữu ích!",
    "author": {
      "username": "tester01",
      "bio": "",
      "image": null,
      "following": false
    }
  }
}

Khi kiểm thử, đừng chỉ kiểm tra “response có JSON”. Hãy đối chiếu tên field, kiểu dữ liệu, field bắt buộc, quan hệ lồng nhau và giá trị nghiệp vụ. Ví dụ, body phải đúng nội dung đã gửi và author phải là người đang đăng nhập.

Bước 7: Xác định status code dự kiến

Swagger của endpoint thêm comment liệt kê các response sau:

Mỗi status code còn gắn với một response schema. Response lỗi của API này sử dụng object errors, vì vậy tester nên kiểm tra cả mã lỗi và nội dung lỗi thay vì chỉ nhìn status code.

Bước 8: Endpoint có yêu cầu authentication không?

Hãy tìm phần Security, biểu tượng ổ khoá hoặc header Authorization. Với endpoint thêm comment, tài liệu liệt kê header authorization và các response 401/403. Token nhận được sau khi đăng nhập được gửi theo dạng:

Authorization: Bearer <token>

Một điểm đáng chú ý trong tài liệu hiện tại: header authorization được mô tả là không bắt buộc ở cấp schema, nhưng endpoint vẫn công bố 401 và 403. Đây chính là tình huống tester không nên chỉ tin một dòng required: false. Hãy đối chiếu mô tả nghiệp vụ và thử request không token, token sai, token hết hạn và token hợp lệ.

Dùng “Try it out” đúng cách

1. Mở endpoint và bấm Try it out.
2. Điền path/query parameter.
3. Nhập request body theo đúng JSON schema.
4. Thêm token nếu endpoint yêu cầu.
5. Bấm Execute.
6. Đọc request URL, curl, status code, response headers và response body.

Try it out giúp khám phá API nhanh, nhưng không thay thế test case. Một lần Execute thành công chỉ chứng minh một bộ dữ liệu đã chạy, chưa bao phủ boundary, validation, authorization, state và các trường hợp lỗi.

Checklist đọc API documentation

• Đúng endpoint cho mục tiêu nghiệp vụ chưa?
• HTTP method là gì?
• Parameter nằm ở đâu và field nào bắt buộc?
• Kiểu dữ liệu, default value và constraint là gì?
• Request body dùng content type và schema nào?
• Response thành công có cấu trúc gì?
• Có những status code và response lỗi nào?
• Có yêu cầu authentication/authorization không?
• Tài liệu có điểm nào thiếu, mâu thuẫn hoặc chưa rõ?

Kết luận

Đọc API documentation không chỉ là tìm một request mẫu để gửi. Tester cần biến từng thông tin trong OpenAPI thành câu hỏi kiểm thử: điều gì bắt buộc, giá trị nào hợp lệ, lỗi nào dự kiến, ai được phép gọi và response phải đúng tới mức nào. Đây là nền tảng để thiết kế test case API có hệ thống ở các phần tiếp theo.