Khi bạn mở một tài liệu API trực tuyến được xuất bản bằng Apidog, bạn sẽ thấy một nút "Try it" bên cạnh mỗi điểm cuối. Nhấp vào đó sẽ làm trượt ra một bảng gỡ lỗi ở phía bên phải của trang, cho phép bạn kiểm tra API trực tiếp trong tài liệu.
Tuy nhiên, khả năng sử dụng của tính năng "Gỡ lỗi" này phụ thuộc phần lớn vào việc bạn đã cấu hình nó tốt như thế nào trong nền tảng. Các yếu tố như thiết lập URL phù hợp, cấu hình xác thực, cấu trúc tham số rõ ràng và dữ liệu ví dụ đầy đủ có tác động đáng kể đến trải nghiệm gỡ lỗi.
Nếu không được cấu hình đúng cách, người dùng có thể mất nhiều thời gian để điền tham số hoặc thậm chí không thực hiện được các cuộc gọi API thành công, điều này hoàn toàn không lý tưởng.
Hãy cùng thảo luận cách cấu hình Apidog hiệu quả để đảm bảo tài liệu trực tuyến đã xuất bản cung cấp trải nghiệm gỡ lỗi tuyệt vời.
Cấu hình URL phù hợp
Thông thường, tài liệu trực tuyến trông ổn nhưng lại thất bại khi bạn nhấp vào nút "Try it" để gửi yêu cầu. Lý do phổ biến nhất là điểm cuối chỉ bao gồm một đường dẫn như /pet/{petId} mà không chọn môi trường thời gian chạy trong quá trình xuất bản.
Điều này dẫn đến các URL yêu cầu không đầy đủ, thiếu giao thức hoặc tên máy chủ, gây ra lỗi khi gửi yêu cầu.
Để khắc phục điều này, hãy đảm bảo người dùng có thể truy cập URL chính xác. Apidog cung cấp ba cách để cấu hình URL cho tài liệu trực tuyến, tùy thuộc vào nhu cầu của bạn.
1. Sử dụng URL cơ sở
Đây là cách tiếp cận được khuyến nghị. Chỉ định đường dẫn trong điểm cuối, ví dụ `/pet/{petId}`, và cấu hình địa chỉ dịch vụ đầy đủ (ví dụ: https://product.example.com) trong phần "Quản lý môi trường" làm URL cơ sở.
Khi xuất bản tài liệu API, hãy chọn môi trường thời gian chạy thích hợp. Apidog sẽ tự động nối URL cơ sở với đường dẫn điểm cuối. Bạn cũng có thể định nghĩa nhiều môi trường thời gian chạy, mỗi môi trường có URL cơ sở riêng.
Trong tài liệu trực tuyến, người dùng có thể nhanh chóng chuyển đổi môi trường từ một danh sách thả xuống, và tất cả các URL điểm cuối sẽ cập nhật tương ứng. Điều này giúp thuận tiện trong việc xác thực API trong các môi trường khác nhau.
Lưu ý: Hãy cẩn thận với các vấn đề về giao thức. Nhiều trình duyệt hạn chế các trang HTTPS gọi API HTTP. Nếu API của bạn sử dụng HTTP, người dùng có thể gặp vấn đề về giao thức chéo khi gỡ lỗi trên trang tài liệu HTTPS.
2. Bao gồm URL đầy đủ trong điểm cuối
Một lựa chọn khác là chỉ định URL đầy đủ trực tiếp trong điểm cuối, ví dụ: https://product.example.com/pet/{petId}.
Điều này đảm bảo URL yêu cầu đầy đủ hiển thị bất kể môi trường thời gian chạy được chọn. Tuy nhiên, việc quản lý các thay đổi địa chỉ máy chủ trở nên cồng kềnh vì bạn sẽ cần cập nhật từng điểm cuối riêng lẻ. Do đó, phương pháp này ít được khuyến nghị hơn.
3. Sử dụng biến trong URL
Nếu bạn muốn người dùng tùy chỉnh URL để gỡ lỗi, bạn có thể sử dụng các biến. Ví dụ, tạo một biến môi trường BaseURL trong phần "Quản lý môi trường" và tham chiếu nó trong URL cơ sở dưới dạng {{BaseURL}}.
Trong tài liệu trực tuyến, người dùng có thể nhấp vào tên biến và sửa đổi nó thành URL mong muốn của họ.
Ngoài ra, bạn có thể định nghĩa các biến trực tiếp trong điểm cuối, ví dụ: {{BaseURL}}/pet/{petId}.
Đối với điểm cuối cụ thể đó trong tài liệu trực tuyến, người dùng có thể đặt giá trị của biến để gửi yêu cầu.
Trước khi xuất bản tài liệu, hãy đảm bảo rằng "giá trị ban đầu" trong môi trường không chứa thông tin nhạy cảm (ví dụ: thông tin xác thực), vì những giá trị này sẽ được bao gồm trong tài liệu đã xuất bản và có thể gây rủi ro về quyền riêng tư.
Cấu hình xác thực phù hợp
Thiết lập xác thực cơ bản
Các yêu cầu điểm cuối thành công thường yêu cầu xác thực. Apidog hỗ trợ nhiều loại xác thực khác nhau, bao gồm Bearer Token, API Key, OAuth2.0 và Basic Auth.
Bạn có thể cấu hình xác thực ở cấp điểm cuối hoặc cấp thư mục bằng cách sử dụng một lược đồ bảo mật hoặc bằng cách thiết lập thủ công.
Ví dụ, khi sử dụng Bearer Token làm loại xác thực, một trường "Token" xuất hiện ở đầu bảng gỡ lỗi trong tài liệu trực tuyến. Người dùng có thể nhập trực tiếp giá trị token mà không cần thêm tiền tố "Bearer" theo cách thủ công. Apidog xử lý điều này tự động, giúp thuận tiện hơn so với việc thêm tiêu đề ủy quyền thủ công.
Ưu điểm của thiết lập này là thông tin xác thực có thể được chia sẻ trên nhiều điểm cuối. Nếu một số điểm cuối sử dụng cùng một lược đồ bảo mật hoặc loại, bạn chỉ cần nhập thông tin đăng nhập một lần. Mọi cập nhật đối với thông tin đăng nhập sẽ tự động áp dụng cho tất cả các điểm cuối liên quan.
Thông tin xác thực được mã hóa và lưu trữ cục bộ trong trình duyệt của người dùng, được quản lý theo phiên và chia sẻ giữa các tab và cửa sổ. Chúng sẽ bị xóa khi trình duyệt đóng, giảm nguy cơ lộ thông tin nhạy cảm trong tài liệu đã xuất bản.
Cấu hình OAuth2.0
Đối với xác thực OAuth2.0, nếu bạn muốn người dùng tạo token trực tiếp trong quá trình gỡ lỗi, hãy cấu hình chi tiết máy chủ ủy quyền (ví dụ: Auth URL, Token URL) trong dự án.
Khi sử dụng lược đồ bảo mật OAuth2.0, người dùng sẽ cần nhập ID client, secret client, v.v., trong quá trình gỡ lỗi. Một cửa sổ bật lên sẽ hướng dẫn họ qua quy trình ủy quyền, và access_token thu được sẽ tự động áp dụng cho các yêu cầu API tiếp theo.
Thiết kế cấu trúc tham số rõ ràng
Hiển thị tham số trong bảng gỡ lỗi
Bảng gỡ lỗi hiển thị các phần tham số một cách thông minh dựa trên thiết kế điểm cuối của bạn. Ví dụ, nếu điểm cuối chỉ định nghĩa các tham số Đường dẫn (Path parameters), bảng gỡ lỗi sẽ chỉ hiển thị phần Đường dẫn, tránh các phần Truy vấn (Query) hoặc Nội dung (Body) không cần thiết.
Sự rõ ràng này giúp người dùng hiểu các tham số cần điền mà không bị phân tâm bởi các phần không liên quan.
Cung cấp ví dụ
Khi thiết kế điểm cuối, hãy định nghĩa chính xác kiểu và các thuộc tính bắt buộc của từng tham số. Bao gồm mô tả và ví dụ rõ ràng, vì những thông tin này sẽ được điền trước vào bảng gỡ lỗi, cải thiện khả năng sử dụng.
Tránh các tiêu đề dư thừa
Nếu điểm cuối định nghĩa các tham số Nội dung (Body parameters), không cần thêm thủ công các tiêu đề như Content-Type: application/json. Apidog tự động xử lý các tiêu đề này trong quá trình yêu cầu.
Tương tự, nếu xác thực được cấu hình, hãy tránh sao chép nó trong các tiêu đề. Cài đặt xác thực sẽ được ưu tiên và sẽ ghi đè bất kỳ cấu hình tiêu đề xung đột nào.
Cung cấp các ví dụ yêu cầu toàn diện
Đối với các điểm cuối có nội dung yêu cầu JSON phức tạp, hãy cung cấp nhiều ví dụ nội dung yêu cầu trong quá trình thiết kế.
Người dùng có thể chọn các ví dụ này từ một menu thả xuống trong bảng gỡ lỗi, tiết kiệm thời gian và giảm lỗi.
Đảm bảo dữ liệu ví dụ giống với các tình huống thực tế, nhưng tránh bao gồm thông tin nhạy cảm. Người dùng có thể sửa đổi các ví dụ này khi cần.
Cấu hình các ví dụ phản hồi rõ ràng
Sau khi gửi yêu cầu, bảng gỡ lỗi hiển thị phản hồi đầy đủ, bao gồm mã trạng thái, tiêu đề và nội dung. Là người tạo tài liệu, hãy cấu hình các ví dụ phản hồi rõ ràng để giúp người dùng hiểu các kết quả có thể xảy ra.
Cung cấp nhiều ví dụ phản hồi cho mỗi điểm cuối, chẳng hạn như thành công (200), yêu cầu không hợp lệ (400) và không được ủy quyền (401).
Đặc biệt chú ý đến các phản hồi lỗi, giải thích rõ ràng các mã lỗi và định dạng thông báo cho các tình huống khác nhau. Điều này giúp người dùng nhanh chóng xác định và giải quyết các vấn đề trong quá trình gỡ lỗi.
Cung cấp mã ví dụ để tích hợp
Mặc dù Apidog tự động tạo mã ví dụ cho các ngôn ngữ lập trình phổ biến, mã được tạo có thể không hoàn toàn phù hợp với nhu cầu kinh doanh của bạn. Trong những trường hợp như vậy, hãy tùy chỉnh các ví dụ.
Bạn có thể cấu hình các ngôn ngữ nào yêu cầu ví dụ được tạo tự động trong "Cài đặt dự án -> Cài đặt tính năng điểm cuối -> Ví dụ mã yêu cầu."
Ngoài ra, bạn có thể viết mã ví dụ tùy chỉnh cho các điểm cuối cụ thể trong phần "Mô tả điểm cuối".
Điều này đảm bảo người dùng thấy cả ví dụ được tạo tự động và ví dụ tùy chỉnh trong tài liệu trực tuyến, giúp việc tích hợp dễ dàng hơn.
Tóm tắt
Trải nghiệm gỡ lỗi của tài liệu trực tuyến phụ thuộc rất nhiều vào cấu hình phù hợp. Bằng cách thiết lập URL, xác thực, cấu trúc tham số và các ví dụ một cách cẩn thận, bạn có thể đảm bảo người dùng nhanh chóng bắt đầu với API của mình mà không bị sa lầy vào các chi tiết kỹ thuật.