Hướng dẫn thiết kế API

Yêu cầu Apidog phiên bản 2.7.22 trở lên.

Apidog đặc biệt khuyến nghị rằng tất cả tài liệu API nên được thiết kế tuân thủ OpenAPI (Swagger) Specification. Bạn có thể tham khảo bài viết này để hiểu vì sao việc tuân theo đặc tả này lại quan trọng đối với API của bạn.

Nhiều tính năng khác của Apidog, chẳng hạn như kiểm tra tuân thủ endpoint được hỗ trợ bởi AI, đặt tên bằng AI, v.v., phụ thuộc vào một hướng dẫn thiết kế API hoàn chỉnh và được xác định rõ ràng. Với một hướng dẫn đã được chuẩn hóa:

Các tính năng khác của Apidog hoạt động hiệu quả hơn

Nhóm của bạn được đồng bộ và tuân theo các nguyên tắc thiết kế nhất quán

Trong Apidog, bạn có thể tạo một hướng dẫn thiết kế API mới bằng cách nhấp vào "+"> "New APl design guidelines" phía trên cây thư mục.

CleanShot 2025-11-05 lúc 17.07.22@2x.png

Khi tạo một hướng dẫn thiết kế API mới, bạn sẽ có hai tùy chọn:

Mẫu ví dụ (được khuyến nghị)
Sử dụng mẫu hướng dẫn thiết kế API hoàn chỉnh do Apidog cung cấp. Đây là lựa chọn được khuyến nghị trong hầu hết các trường hợp. Mẫu này dựa trên OAS (OpenAPI Specification) và được biên soạn có tham khảo các thực tiễn tốt nhất của Microsoft về thiết kế API.

Mẫu trống
Tạo một mẫu thiết kế trống. Tùy chọn này chỉ cung cấp cấu trúc cơ bản của một đặc tả mà không có nội dung chi tiết. Sau đó, bạn có thể viết hướng dẫn thiết kế API riêng của nhóm mình. Nếu nhóm của bạn đã có các tiêu chuẩn và thực tiễn tốt nhất được thiết lập, đây có thể là điểm khởi đầu phù hợp hơn.

Sau khi chọn, xem trước và xác nhận mẫu phù hợp với nhu cầu của bạn, một hướng dẫn thiết kế API mới sẽ được tạo trong dự án của bạn. Bạn có thể tùy chỉnh hoàn toàn nội dung của hướng dẫn này khi cần. Hướng dẫn thiết kế sẽ được hiển thị ở đầu cây thư mục để nhắc nhở tất cả thành viên trong nhóm về tầm quan trọng của các đặc tả.

Tìm hiểu thêm: Kiểm tra tuân thủ endpoint.