Với plugin IDEA của Apidog hoặc một số plugin Swagger, bạn có thể dễ dàng tạo tài liệu API từ mã nguồn, giải quyết vấn đề viết tài liệu từ đầu.
Tuy nhiên, ngay cả sau khi các điểm cuối được viết và tài liệu được tạo ra, bạn có thể vẫn cảm thấy không chắc chắn: Thiết kế API đã đủ tốt chưa? Tài liệu đã được chuẩn hóa chưa? Có những lĩnh vực nào có thể cải thiện thêm không?
Đặc biệt trong làm việc nhóm, bạn muốn tài liệu API của mình dễ hiểu đối với đồng đội ngay từ cái nhìn đầu tiên. Sự rõ ràng trong đặt tên và tính đầy đủ của thông tin ảnh hưởng trực tiếp đến trải nghiệm của họ khi sử dụng API của bạn.
Apidog gần đây đã triển khai một số tính năng AI để giúp bạn tối ưu hóa thêm tài liệu API ở giai đoạn này. Cho dù bạn đang cải thiện chi tiết điểm cuối hiện có hay nhập tài liệu API hiện có từ nơi khác, AI đều có thể đưa ra các đề xuất thiết thực.
Dưới đây, chúng tôi sẽ hướng dẫn cách sử dụng AI trong Apidog để tạo tài liệu API được chuẩn hóa hơn. Trước khi bắt đầu, hãy đảm bảo bạn đã cập nhật Apidog lên phiên bản mới nhất, bật các tính năng AI và cấu hình mô hình AI.
Nhập từ tài liệu hiện có
Đôi khi bạn cần di chuyển tài liệu API từ các nguồn khác vào Apidog. Nếu tài liệu ở định dạng chuẩn, Apidog hỗ trợ nhiều phương pháp nhập gốc: bạn có thể tạo tài liệu từ mã nguồn thông qua plugin IDEA, nhập thông số kỹ thuật OpenAPI/Swagger, hoặc di chuyển từ các công cụ khác như Postman.
Nhưng trong một số trường hợp, tài liệu của bạn có thể không ở các định dạng chuẩn này. Ví dụ, nhóm trước đây đã ghi lại các điểm cuối trong Markdown, sắp xếp mô tả trường trong Word, hoặc tìm thấy định nghĩa điểm cuối trong nhật ký trò chuyện hoặc email. Việc nhập thủ công từng trường từ các nguồn không chuẩn này vào Apidog có thể rất khó khăn.
Trong tình huống này, bạn có thể sử dụng tính năng Sửa đổi schema bằng AI để hỗ trợ nhập dữ liệu. Giả sử bạn có nội dung Markdown như thế này:
| name | desc | type | required |
| ---------- | --------------------------------------------------------------------------- | --------- | -------- |
| usePaging | Whether to enable pagination | boolean | true |
| offset | Starting position (required when pagination is enabled) | int | false |
| pageSize | Number of items per page (required when pagination is enabled) | int | false |
| minPrice | Minimum price (unit: cents) | int | false |
| maxPrice | Maximum price (unit: cents) | int | false |
| brand | Brand code | string | false |
| categoryId | Product category ID | int | false |
| sortRule | Sorting rule: 1 → Sales priority, 2 → Price ascending, 3 → Price descending | enum(int) | false |
| keyword | Search keyword (fuzzy match on product name) | string | false |Chỉ cần sao chép các tham số và hỏi AI: "Chuyển đổi nội dung này thành các tham số điểm cuối, đảm bảo xác định kiểu dữ liệu và các trường bắt buộc."
AI sẽ tự động phát hiện tên trường, kiểu dữ liệu, trạng thái bắt buộc và mô tả, sau đó chuyển đổi mọi thứ sang định dạng schema chuẩn của Apidog. Nếu có các enum, AI cũng sẽ sắp xếp chúng thành các kiểu enum phù hợp cho bạn.
AI giúp bạn tinh chỉnh chi tiết API
Sau khi nhập thông tin cơ bản, bước tiếp theo là tinh chỉnh các chi tiết.
Nếu bạn không chắc chắn về tên một trường, hãy sử dụng tính năng đặt tên bằng AI. AI sẽ cung cấp các gợi ý đặt tên chính xác hơn theo thông số kỹ thuật điểm cuối và hướng dẫn thiết kế API.
Bạn cũng có thể sử dụng AI để tự động hoàn thành mô tả trường nhằm có những giải thích rõ ràng và đầy đủ hơn.
Tạo dữ liệu giả lập là một điểm mạnh khác của AI. Thông thường chúng ta biết một trường đại diện cho điều gì nhưng không chắc chắn nên sử dụng giá trị ví dụ nào. AI sẽ tự động tạo dữ liệu ví dụ hợp lý dựa trên kiểu và mô tả của trường.
Kiểm tra tính đầy đủ của tài liệu API: Tránh thiếu sót
Khi tài liệu có vẻ gần như hoàn chỉnh, bạn có thể vẫn tự hỏi liệu có bất kỳ thông tin quan trọng nào bị thiếu không. Tại thời điểm này, hãy sử dụng Tính năng kiểm tra tính đầy đủ của tài liệu API của Apidog để xem có điều gì bị bỏ sót không.
AI sẽ quét tài liệu API hiện có của bạn từ nhiều góc độ để xác định thông tin bị thiếu hoặc không đầy đủ. Sau đó, nó tạo ra một báo cáo chi tiết chấm điểm từng mục đánh giá, giúp bạn nhanh chóng biết được tài liệu API của mình cần cải thiện ở đâu.
Báo cáo không chỉ cho bạn biết phải làm gì—nó còn giải thích lý do tại sao. Chẳng hạn, bạn có thể đã ghi lại định dạng phản hồi thành công nhưng không có các kịch bản lỗi có thể xảy ra; bạn có thể có các mô tả trường cơ bản nhưng thiếu các ràng buộc sử dụng hoặc yêu cầu định dạng.
Bạn có thể cải thiện tài liệu API của mình bằng cách làm theo các gợi ý được cung cấp trong báo cáo.
Kiểm tra tuân thủ điểm cuối: Đảm bảo tính nhất quán
Ngoài việc đầy đủ, tài liệu API cũng cần được chuẩn hóa tốt. Trong một điểm cuối duy nhất, việc đặt tên phải tuân theo một phong cách nhất quán, kiểu trường phải được định nghĩa rõ ràng và chính xác, và cấu trúc phản hồi phải hợp lý. Những chi tiết này đóng vai trò quan trọng trong việc làm cho tài liệu của bạn dễ đọc và dễ bảo trì.
Tính năng kiểm tra tuân thủ điểm cuối của Apidog kiểm tra tài liệu của bạn từ nhiều góc độ. Ví dụ, nếu một số trường được đặt tên bằng động từ trong khi những trường khác sử dụng danh từ, AI sẽ đánh dấu sự không nhất quán và đề xuất một phong cách đặt tên thống nhất.
Nó cũng kiểm tra xem các định nghĩa trường có tuân thủ các tiêu chuẩn nhất quán hay không, chẳng hạn như tránh các kiểu viết hoa/thường lẫn lộn, việc sử dụng đồng thời dấu gạch dưới và camelCase, hoặc các từ viết tắt không nhất quán, và sau đó cung cấp các gợi ý rõ ràng về cách khắc phục những vấn đề này.
Tóm tắt
Tạo tài liệu API rõ ràng và chuẩn hóa là điều cần thiết. Các tính năng như tạo trường hợp kiểm thử bằng AI, phụ thuộc vào chất lượng tài liệu của bạn—chúng càng đầy đủ và nhất quán, các trường hợp kiểm thử được tạo ra sẽ càng chính xác và hữu ích.
Bạn không cần phải sử dụng mọi tính năng AI cùng một lúc hoặc đại tu quy trình làm việc hiện tại của mình.
Đây là một quá trình dần dần. Bạn có thể bắt đầu bằng cách nhập tài liệu hiện có của mình và sau đó từ từ áp dụng các tính năng AI để cải thiện và tinh chỉnh nó. Nếu bạn không chắc chắn về một gợi ý, bạn có thể giữ nguyên và xem xét lại sau khi có thêm ngữ cảnh.
Theo thời gian, bạn sẽ tự nhiên hiểu rõ hơn về các tiêu chuẩn tài liệu API. AI không chỉ giúp khắc phục các vấn đề tức thời—nó còn giúp bạn phát triển thói quen tạo tài liệu tốt hơn.