Kiểm tra mức độ hoàn chỉnh của tài liệu API

INFO

Xem Bắt đầu với các tính năng AI để biết các yêu cầu thiết lập. Lưu ý: Tính năng này yêu cầu Apidog phiên bản 2.7.55 trở lên.

Tổng quan

Bạn có thể sử dụng AI để chạy API Documentation Completeness Check trên tài liệu API hiện tại của mình và tạo một báo cáo đánh giá chi tiết. Dựa trên báo cáo này, bạn có thể tinh chỉnh và cải thiện tài liệu — giúp việc cộng tác trở nên mượt mà hơn, tài liệu dễ đọc hơn, và tất cả các tính năng AI hoạt động hiệu quả hơn nhờ thông số kỹ thuật endpoint chính xác hơn.

Nội dung được kiểm tra

Trước khi chạy API Documentation Completeness Check, bạn nên xem xét liệu các mô tả và định nghĩa trong tài liệu API hiện tại đã đầy đủ hay chưa. Quá trình kiểm tra phân tích các khía cạnh sau:

1. Định nghĩa cơ bản

Kiểm tra xem tài liệu endpoint có chỉ định rõ ràng và chính xác các nội dung sau hay không:

Thành phần	Mục đích
Phương thức yêu cầu	Xác định phương thức HTTP (GET, POST, PUT, DELETE) để xác định ngữ nghĩa của yêu cầu, tính lũy đẳng và cấu trúc tham số
Đường dẫn yêu cầu	Đường dẫn URL đầy đủ (không bao gồm base URL) để xác định duy nhất endpoint và suy luận cấu trúc tham số đường dẫn
Tên và mô tả endpoint	Phần giải thích ngắn gọn về mục đích của endpoint nhằm giúp người đọc và AI hiểu logic nghiệp vụ

2. Mô tả tham số

Kiểm tra xem tài liệu endpoint có chỉ định rõ ràng và chính xác các nội dung sau hay không:

Thành phần	Mục đích
Tên tham số	Đảm bảo cấu trúc tham số đầy đủ, cách đặt tên nhất quán và mỗi tham số nằm đúng vị trí (Params, Body, Headers, Cookies)
Ví dụ	Cung cấp các giá trị đầu vào mẫu hợp lệ để giúp hiểu các giá trị, định dạng, kiểu dữ liệu và ý nghĩa nghiệp vụ điển hình
Mô tả	Giải thích ý nghĩa, mục đích và các tình huống nghiệp vụ của tham số

Thông tin cơ bản của các tham số yêu cầu có thể được tạo hoặc sửa đổi với sự hỗ trợ của AI.

3. Ràng buộc tham số

Kiểm tra xem tài liệu endpoint có chỉ định rõ ràng và chính xác các nội dung sau hay không:

Ràng buộc	Mục đích
Bắt buộc/Có thể null	Cho biết liệu một tham số có bắt buộc hay không và liệu giá trị null có được phép hay không
Enums/Const	Liệt kê các giá trị enum hoặc hằng số có thể có và ý nghĩa của chúng
Giá trị biên	Cung cấp giá trị tối thiểu/tối đa, giới hạn độ dài và các ràng buộc khác
Định dạng	Mô tả các định dạng đặc biệt (date-time, email, uuid, binary, int64, json-string, v.v.)

4. Phản hồi

Kiểm tra xem tài liệu API có chỉ định rõ ràng và chính xác các nội dung sau hay không:

Thành phần	Mục đích
Response Body	Cung cấp cấu trúc đầy đủ cho loại nội dung phản hồi, phần giải thích trường, mã trạng thái HTTP và mã lỗi

Thông tin cơ bản của phản hồi cũng có thể được tạo hoặc sửa đổi với sự hỗ trợ của AI.

Kiểm tra mức độ hoàn chỉnh của tài liệu API

Bạn có thể tìm thấy tính năng API Documentation Completeness Check ở góc trên bên phải của trang tài liệu endpoint. Nhấp vào đó để bắt đầu kiểm tra.

Nếu tính năng bị làm mờ, điều đó có nghĩa là tính năng này hiện đang bị vô hiệu hóa. Quản trị viên nhóm hoặc tổ chức trước tiên phải bật tính năng này trong phần cài đặt. Ngoài ra, hãy đảm bảo client Apidog của bạn đã được cập nhật lên phiên bản mới nhất.

Sau khi bạn bắt đầu kiểm tra, AI sẽ đánh giá tài liệu endpoint hiện tại dựa trên các tiêu chí được xác định trước. Sau đó, AI tạo một báo cáo chi tiết với điểm số, phần giải thích và các đề xuất tối ưu hóa có thể thực hiện cho từng hạng mục đánh giá — giúp bạn nhanh chóng nhận biết nội dung nào còn thiếu và cách cải thiện.

Kiểm tra mức độ hoàn chỉnh của tài liệu API

Tổng quan#

Nội dung được kiểm tra#

1. Định nghĩa cơ bản#

2. Mô tả tham số#

3. Ràng buộc tham số#

4. Phản hồi#

Kiểm tra mức độ hoàn chỉnh của tài liệu API#

Tổng quan

Nội dung được kiểm tra

1. Định nghĩa cơ bản

2. Mô tả tham số

3. Ràng buộc tham số

4. Phản hồi

Kiểm tra mức độ hoàn chỉnh của tài liệu API