Thử API từ tài liệu OpenAPI: nạp spec, chọn endpoint và gửi yêu cầu thật
Công cụ nhận nội dung tài liệu OpenAPI hoặc Swagger ở định dạng JSON, tách ra danh sách endpoint kèm phương thức và mô tả, rồi cho bạn điền tham số, thân yêu cầu và thông tin xác thực để gửi một yêu cầu thật tới máy chủ. Yêu cầu được phát đi trực tiếp từ trình duyệt của bạn, nên phần lớn vướng mắc khi dùng nằm ở chính sách chia sẻ tài nguyên giữa các nguồn.
Tính năng nổi bật
- Dán nội dung tài liệu OpenAPI 3 hoặc Swagger 2 ở định dạng JSON rồi tách tự động thành danh sách endpoint
- Nhận diện năm phương thức GET, POST, PUT, PATCH và DELETE cùng phần tóm tắt, mô tả và nhãn phân nhóm của từng endpoint
- Tự lấy địa chỉ máy chủ đầu tiên trong phần servers làm địa chỉ gốc, và cho phép sửa lại bằng tay
- Tự sinh ô nhập cho tham số đường dẫn và tham số truy vấn, tự thay giá trị vào chỗ giữ chỗ trong đường dẫn
- Tự điền thân yêu cầu mẫu khi tài liệu có khai báo ví dụ cho kiểu nội dung JSON
- Bốn kiểu xác thực: không dùng, Bearer, Basic tự mã hóa tên đăng nhập và mật khẩu, hoặc khóa API đặt trong tiêu đề hay trong chuỗi truy vấn
- Hiển thị đầy đủ mã trạng thái, toàn bộ tiêu đề phản hồi, phần thân đã định dạng lại và thời gian thực hiện
- Nút sao chép phần thân phản hồi và nút tải tài liệu đã chuẩn hóa về dạng JSON có thụt lề
Khoảng cách giữa tài liệu và hành vi thật của API
Tài liệu OpenAPI mô tả API nên như thế nào, còn máy chủ thì trả về những gì nó thật sự trả về, và hai thứ này lệch nhau thường xuyên hơn người ta muốn thừa nhận: một trường bị đổi tên nhưng tài liệu chưa cập nhật, một tham số ghi là bắt buộc nhưng thực tế bỏ trống vẫn chạy, một mã lỗi có trong tài liệu nhưng máy chủ trả mã khác. Cách duy nhất để biết là gửi một yêu cầu thật rồi nhìn phản hồi. Công cụ này rút ngắn quãng đường từ tài liệu tới yêu cầu thật: bạn không phải tự gõ lại đường dẫn, không phải nhớ tham số nào đặt trong đường dẫn và tham số nào đặt sau dấu hỏi, không phải tự dựng chuỗi xác thực. Nó phù hợp cho những lần thử nhanh khi đang đọc tài liệu của một API lạ, khi cần kiểm tra một endpoint sau khi triển khai, hay khi cần đưa cho đồng nghiệp thấy chính xác một yêu cầu trả về gì. Với công việc kiểm thử có tổ chức và lặp lại, bạn vẫn cần một phần mềm chuyên dụng có lưu bộ sưu tập và biến môi trường.
Lợi ích khi sử dụng
- Không phải gõ lại đường dẫn và tham số từ tài liệu nên giảm hẳn lỗi gõ nhầm
- Thấy ngay sự lệch giữa tài liệu và hành vi thật của máy chủ
- Thử được cả bốn kiểu xác thực phổ biến mà không phải tự dựng chuỗi tiêu đề
- Có thời gian phản hồi kèm theo nên phát hiện sớm endpoint chậm bất thường
- Mã thông báo và mật khẩu bạn nhập chỉ nằm trong trình duyệt và đi thẳng tới máy chủ bạn chỉ định
Cách thử một endpoint
- 1Dán toàn bộ nội dung tài liệu OpenAPI ở định dạng JSON vào ô nhập rồi bấm phân tích, thẻ danh sách endpoint sẽ mở ra nếu cấu trúc hợp lệ.
- 2Chọn một endpoint trong danh sách, công cụ tự chuyển sang thẻ thử nghiệm và sinh sẵn ô nhập cho từng tham số.
- 3Kiểm tra lại địa chỉ gốc ở đầu thẻ thử nghiệm, sửa lại nếu bạn muốn gọi vào môi trường thử nghiệm thay vì môi trường ghi trong tài liệu.
- 4Điền tham số, chỉnh thân yêu cầu nếu là phương thức có thân, rồi mở phần xác thực để chọn đúng kiểu và điền khóa hoặc mã thông báo.
- 5Bấm gửi và đọc phản hồi theo thứ tự mã trạng thái, tiêu đề rồi mới tới thân, vì mã trạng thái và tiêu đề thường đã đủ để biết vấn đề nằm ở đâu.
Rào cản lớn nhất khi thử API từ trình duyệt: chính sách nguồn gốc chéo
Yêu cầu ở đây được phát đi bằng cơ chế fetch của trình duyệt, nghĩa là nó chịu toàn bộ ràng buộc mà trình duyệt áp cho mã lệnh của một trang web khi gọi sang tên miền khác. Nếu máy chủ API không trả về tiêu đề cho phép nguồn gốc của trang này, trình duyệt sẽ chặn phản hồi và bạn nhận một lỗi chung chung kiểu không gửi được yêu cầu, dù máy chủ đã nhận và xử lý bình thường. Tình huống này gây bối rối vì cùng một yêu cầu chạy hoàn hảo trong phần mềm kiểm thử cài trên máy, nơi không có trình duyệt đứng giữa. Thêm một lớp nữa: khi bạn đặt tiêu đề kiểu nội dung là JSON hoặc thêm tiêu đề xác thực, yêu cầu không còn thuộc nhóm đơn giản nên trình duyệt gửi trước một yêu cầu thăm dò bằng phương thức OPTIONS, và máy chủ phải trả lời đúng yêu cầu thăm dò đó thì yêu cầu thật mới được gửi. Vì vậy khi gặp lỗi, việc đầu tiên nên làm là mở bảng Network trong công cụ nhà phát triển để xem yêu cầu thăm dò có được trả lời hay không.
Định dạng tài liệu mà công cụ đọc được và những chỗ hụt
Công cụ dùng bộ phân tích JSON, nên chỉ nhận tài liệu ở định dạng JSON. Rất nhiều dự án viết tài liệu bằng YAML cho dễ đọc, và bạn phải chuyển sang JSON trước khi dán vào. Công cụ cũng không nhận đường dẫn tới tài liệu, tức là không tự tải giúp bạn tệp mô tả từ một địa chỉ, bạn phải mở địa chỉ đó rồi sao chép nội dung. Về phiên bản, công cụ lấy địa chỉ gốc từ mảng servers, vốn chỉ có trong OpenAPI phiên bản 3; tài liệu Swagger phiên bản 2 dùng ba trường riêng lẻ để mô tả máy chủ nên ô địa chỉ gốc sẽ trống và bạn phải tự điền. Về phần thân yêu cầu, công cụ chỉ lấy được ví dụ khi tài liệu khai báo ví dụ trực tiếp cho kiểu nội dung JSON; nếu tài liệu chỉ mô tả cấu trúc dữ liệu mà không kèm ví dụ thì ô thân sẽ trống và bạn phải tự viết. Ngoài ra tham số khai báo nằm trong tiêu đề hoặc trong cookie không được sinh ô nhập, bạn phải thêm chúng bằng tay ở phần tiêu đề.
Bốn kiểu xác thực và điều cần biết về từng kiểu
Kiểu Bearer đặt mã thông báo vào tiêu đề xác thực với tiền tố Bearer, đây là dạng phổ biến nhất hiện nay và cũng là dạng dùng cho mã thông báo JWT. Kiểu Basic ghép tên đăng nhập và mật khẩu bằng dấu hai chấm rồi mã hóa base64; cần nói rõ base64 không phải mã hóa bảo mật mà chỉ là cách biểu diễn, ai bắt được gói tin đều giải ngược ra được, nên kiểu này chỉ an toàn khi chạy trên kết nối đã mã hóa. Kiểu khóa API cho bạn chọn đặt khóa vào tiêu đề với tên tùy ý hoặc gắn vào chuỗi truy vấn; đặt vào chuỗi truy vấn tiện hơn nhưng khóa sẽ lọt vào nhật ký máy chủ, vào lịch sử trình duyệt và vào tiêu đề giới thiệu khi trang chuyển hướng, nên hãy ưu tiên đặt vào tiêu đề khi API cho phép cả hai. Một lưu ý an toàn chung: mọi giá trị bạn nhập chỉ nằm trong bộ nhớ của trang và đi thẳng tới máy chủ bạn chỉ định, nhưng đừng nhập mã thông báo của môi trường chính thức trên máy dùng chung, và hãy tải lại trang sau khi thử xong để xóa chúng khỏi bộ nhớ.
Đọc phản hồi theo thứ tự mã trạng thái, tiêu đề rồi mới tới thân
Mã trạng thái nói cho bạn biết loại vấn đề trước khi cần đọc bất kỳ dòng dữ liệu nào. Nhóm 200 là thành công, trong đó 201 nghĩa là đã tạo mới và thường kèm tiêu đề chỉ tới tài nguyên vừa tạo, 204 nghĩa là thành công nhưng không có nội dung nên thân rỗng là đúng chứ không phải lỗi. Nhóm 400 là lỗi từ phía yêu cầu: 400 là dữ liệu gửi lên sai định dạng, 401 là chưa xác thực hoặc mã thông báo hết hạn, 403 là đã xác thực nhưng không đủ quyền, 404 là sai đường dẫn hoặc tài nguyên không tồn tại, 415 là kiểu nội dung không được chấp nhận, 422 là dữ liệu đúng định dạng nhưng không hợp lệ về nghiệp vụ, 429 là bị giới hạn tần suất. Nhóm 500 là lỗi phía máy chủ, và khi gặp nhóm này thì không có gì để sửa ở phía bạn ngoài việc báo cho đội phát triển kèm thời điểm và nội dung yêu cầu. Phần tiêu đề phản hồi cũng đáng đọc: kiểu nội dung cho biết định dạng thật, các tiêu đề về giới hạn tần suất cho biết bạn còn bao nhiêu lượt gọi.
Những gì công cụ không làm và khi nào nên chuyển sang phần mềm khác
Công cụ không lưu lịch sử yêu cầu, không lưu bộ sưu tập, không có biến môi trường để đổi nhanh giữa máy chủ thử nghiệm và máy chủ chính thức, và tải lại trang là mất toàn bộ những gì bạn đã nhập. Nó không hỗ trợ tải tệp lên theo kiểu biểu mẫu nhiều phần, không hỗ trợ hai phương thức HEAD và OPTIONS, không tự động lấy mã thông báo qua luồng ủy quyền, không chạy chuỗi nhiều yêu cầu nối tiếp nhau, và không có phần kiểm tra tự động để khẳng định phản hồi đúng hay sai. Nó cũng không sinh mã nguồn mẫu cho ngôn ngữ lập trình. Vì vậy hãy dùng nó cho những lần thử lẻ trong lúc đọc tài liệu hoặc lúc vừa triển khai xong. Khi công việc chuyển sang giai đoạn kiểm thử lặp lại nhiều lần, chạy theo bộ, hoặc tích hợp vào quy trình tự động, bạn cần một phần mềm kiểm thử API cài trên máy hoặc một công cụ dòng lệnh, nơi không có ràng buộc nguồn gốc chéo và có chỗ lưu cấu hình.
Câu hỏi thường gặp (FAQ)
Vì sao gửi yêu cầu thì báo lỗi trong khi API vẫn chạy tốt?
Gần như luôn là do chính sách nguồn gốc chéo. Yêu cầu được phát từ trình duyệt nên máy chủ API phải trả về tiêu đề cho phép nguồn gốc của trang này, nếu không trình duyệt sẽ chặn phản hồi và bạn chỉ thấy một lỗi chung chung. Hãy mở bảng Network của trình duyệt để xem yêu cầu có thật sự bị chặn hay không.
Yêu cầu thăm dò bằng phương thức OPTIONS là gì?
Khi yêu cầu của bạn có tiêu đề kiểu nội dung là JSON hoặc có tiêu đề xác thực, nó không còn thuộc nhóm yêu cầu đơn giản, nên trình duyệt gửi trước một yêu cầu OPTIONS để hỏi máy chủ có cho phép hay không. Nếu máy chủ không trả lời đúng yêu cầu thăm dò này, yêu cầu thật sẽ không bao giờ được gửi đi.
Công cụ có nhận tài liệu viết bằng YAML không?
Không. Bộ phân tích chỉ đọc JSON, nên tài liệu viết bằng YAML phải được chuyển sang JSON trước khi dán vào. Nhiều trình soạn thảo và công cụ dòng lệnh làm việc này trong một bước, hoặc bạn có thể lấy bản JSON mà chính máy chủ tài liệu của dự án phục vụ sẵn.
Dán được đường dẫn tới tệp tài liệu thay vì dán nội dung không?
Không. Công cụ chỉ nhận nội dung dán trực tiếp, không tự tải tài liệu từ một địa chỉ. Bạn hãy mở địa chỉ đó trên một thẻ khác, sao chép toàn bộ nội dung rồi dán vào. Cách này cũng tránh cho bạn một lớp vướng mắc nguồn gốc chéo nữa ở khâu tải tài liệu.
Vì sao ô địa chỉ gốc để trống sau khi phân tích tài liệu?
Vì tài liệu của bạn nhiều khả năng là Swagger phiên bản 2, vốn mô tả máy chủ bằng các trường riêng lẻ chứ không dùng mảng servers như OpenAPI phiên bản 3. Trong trường hợp này bạn tự điền địa chỉ gốc, gồm giao thức, tên miền và phần đường dẫn cơ sở nếu có.
Vì sao thân yêu cầu không tự điền sẵn?
Công cụ chỉ lấy được ví dụ khi tài liệu khai báo ví dụ trực tiếp cho kiểu nội dung JSON của endpoint đó. Nếu tài liệu chỉ mô tả cấu trúc dữ liệu qua sơ đồ mà không kèm ví dụ, ô thân sẽ trống và bạn phải tự viết dựa theo mô tả các trường trong tài liệu.
Tham số nằm trong tiêu đề có được sinh ô nhập không?
Không, công cụ chỉ sinh ô nhập cho tham số khai báo nằm trong đường dẫn và trong chuỗi truy vấn. Tham số nằm trong tiêu đề hoặc cookie thì bạn phải tự thêm ở phần tiêu đề của yêu cầu. Hãy đối chiếu lại danh sách tham số trong tài liệu để không bỏ sót.
Xác thực kiểu Basic có an toàn không?
Chỉ an toàn khi chạy trên kết nối đã mã hóa. Kiểu này ghép tên đăng nhập và mật khẩu rồi mã hóa base64, mà base64 là cách biểu diễn chứ không phải mã hóa bảo mật, ai bắt được gói tin đều giải ngược ra được nguyên văn mật khẩu. Trên kết nối không mã hóa thì kiểu này tương đương gửi mật khẩu ở dạng rõ.
Nên đặt khóa API vào tiêu đề hay vào chuỗi truy vấn?
Ưu tiên tiêu đề khi API chấp nhận cả hai. Khóa đặt trong chuỗi truy vấn sẽ nằm lại trong nhật ký máy chủ, trong lịch sử trình duyệt và có thể lọt sang bên thứ ba qua tiêu đề giới thiệu khi trang chuyển hướng. Đặt trong tiêu đề tránh được cả ba đường rò rỉ đó.
Mã thông báo tôi nhập có bị lưu lại không?
Không. Chúng chỉ nằm trong bộ nhớ tạm của trang và được gắn vào yêu cầu gửi thẳng tới máy chủ bạn chỉ định, tải lại trang là mất. Dù vậy vẫn nên tránh dùng mã thông báo của môi trường chính thức trên máy dùng chung, và nên dùng mã thông báo có thời hạn ngắn khi thử nghiệm.
Phản hồi trả về mã 204 với thân rỗng có phải lỗi không?
Không, đó là hành vi đúng. Mã 204 nghĩa là yêu cầu thành công và máy chủ cố ý không trả về nội dung nào, thường gặp ở các thao tác xóa hoặc cập nhật. Tương tự, mã 201 nghĩa là đã tạo mới và bạn nên xem tiêu đề phản hồi để lấy địa chỉ của tài nguyên vừa được tạo.
Công cụ có lưu lại các yêu cầu tôi đã thử không?
Không. Không có lịch sử, không có bộ sưu tập và không có biến môi trường, tải lại trang là mất hết. Nếu bạn cần chạy đi chạy lại một bộ yêu cầu, đổi nhanh giữa các môi trường hoặc đưa vào quy trình tự động, hãy dùng phần mềm kiểm thử API cài trên máy hoặc công cụ dòng lệnh.
Từ khóa liên quan
- thử api online
- openapi là gì
- swagger là gì
- công cụ test api
- gửi request api từ trình duyệt
- lỗi cors khi gọi api
- preflight options request
- bearer token là gì
- basic authentication
- api key trong header
- mã trạng thái http
- lỗi 401 và 403 khác nhau
- tài liệu api rest
- endpoint api
- request body json
- query parameter và path parameter
- kiểm thử api
- openapi 3 và swagger 2
- thời gian phản hồi api
- debug api không trả dữ liệu
