Bài viết này giới thiệu các khái niệm cốt lõi trong Apidog, một công cụ API-first được thiết kế để thiết kế, kiểm thử và cộng tác API một cách hiệu quả. Nhiều khái niệm khác với các sản phẩm tương tự như Postman. Việc hiểu rõ các khái niệm này sẽ giúp bạn điều hướng quy trình làm việc của Apidog một cách hiệu quả.Dự án#
Dự án trong Apidog là đơn vị cộng tác chính, chứa các module, môi trường, kịch bản kiểm thử, v.v. Dự án đóng vai trò là vùng chứa cho toàn bộ công việc liên quan đến API trong một nhóm.Các thành phần chính của một dự án#
Module: Các nhóm logic gồm endpoint và các thành phần liên quan.
Môi trường: Các bộ biến cho các giai đoạn triển khai khác nhau (ví dụ: phát triển, staging, production).
Kịch bản kiểm thử: Các tập hợp yêu cầu dùng cho kiểm thử tự động.
Đặc tả endpoint: Tài liệu API dựa trên các tiêu chuẩn OpenAPI/Swagger.
So sánh với Postman#
| Khái niệm trong Apidog | Tương đương trong Postman | Mô tả |
|---|
| Dự án | Workspace | Đơn vị tổ chức cấp cao nhất cho hoạt động cộng tác. |
| Module | Collection Folder | Nhóm các endpoint liên quan. |
| Nhóm | Team | Các tính năng truy cập và cộng tác dùng chung. |
Dự án cho phép cộng tác liền mạch, cho phép nhiều người dùng làm việc đồng thời trên API trong khi vẫn duy trì kiểm soát phiên bản và quyền truy cập.
Module#
Module tổ chức các endpoint theo logic trong một dự án, tương tự như một "dịch vụ" trong kiến trúc microservices. Mỗi module đại diện cho một tệp đặc tả OpenAPI độc lập.Tính năng của một module#
Chứa các endpoint, schema, phản hồi và cơ chế bảo mật liên quan.
Được cấu hình với Base URL theo từng môi trường để tự động tạo URL.
Hỗ trợ các thao tác nhập/xuất ở cấp module nhằm tuân thủ tiêu chuẩn tốt hơn.
Khi nào nên sử dụng module#
Đối với microservices: Mỗi dịch vụ là một module riêng biệt.
Đối với nhiều API: Nhóm endpoint theo chức năng hoặc miền nghiệp vụ.
Mặc định: Dự án mới bắt đầu với một module; thêm module khi cần cho nhiều base URL.
Module phù hợp với OpenAPI Specification (OAS), giúp tích hợp với các công cụ khác và duy trì ranh giới API rõ ràng.
Endpoint#
Endpoint là thành phần cốt lõi trong cách tiếp cận API-first của Apidog, đại diện cho một thao tác API cụ thể (ví dụ: GET /users/{id}).Quản lý endpoint#
Được nhóm trong cấu trúc thư mục để tổ chức.
Được liên kết với endpoint case cho các ví dụ yêu cầu đã lưu.
Khác biệt so với Postman#
| Khía cạnh | Apidog (dựa trên endpoint) | Postman (dựa trên yêu cầu) |
|---|
| Đơn vị cơ bản | Endpoint (đặc tả API) | Yêu cầu (lệnh gọi riêng lẻ) |
| Thay đổi đặc tả | Tự động cập nhật case và kiểm thử | Cần viết lại thủ công |
| Cấu trúc | Phần mở rộng OAS kèm gỡ lỗi | Đặc tả và yêu cầu tách biệt |
Trong Apidog, các thay đổi đối với đặc tả endpoint sẽ tự động lan truyền đến tất cả case phụ thuộc, giúp giảm chi phí bảo trì thông qua cách tiếp cận dựa trên đặc tả này.
Môi trường#
Môi trường quản lý các biến và base URL cho những ngữ cảnh triển khai khác nhau, cho phép chuyển đổi liền mạch giữa dev, staging và production.Tính năng chính#
Chứa các biến môi trường cho giá trị động.
Hỗ trợ nhiều Base URL trên mỗi môi trường cho microservices. Tự động xây dựng URL: Base URL + Endpoint Path.
Ví dụ về Base URL#
Giả sử một dự án có ba dịch vụ:| Dịch vụ | Base URL (Prod) | Đường dẫn endpoint | URL đầy đủ |
|---|
| Người dùng | https://user.example.com | GET /user/{id} | https://user.example.com/user/{id} |
| Đơn hàng | https://order.example.com | GET /order/{id} | https://order.example.com/order/{id} |
| Sản phẩm | https://product.example.com | GET /product/{id} | https://product.example.com/product/{id} |
Không cần dùng placeholder {{BaseUrl}} thủ công; Apidog tự động phát hiện module và áp dụng base URL chính xác.
Yêu cầu#
Yêu cầu là một lệnh gọi API độc lập, không gắn với đặc tả endpoint, tương tự như các yêu cầu của Postman.Khả năng của yêu cầu#
Phân tích các yêu cầu thành công thành đặc tả endpoint. Sử dụng cho kiểm thử đột xuất hoặc các API chưa được lập tài liệu.
Yêu cầu mang lại sự linh hoạt cho các tình huống mà đặc tả API chưa được định nghĩa trước, thu hẹp khoảng cách giữa quy trình làm việc design-first và request-first.
Kịch bản kiểm thử#
Kịch bản kiểm thử thực thi các lô yêu cầu, tương tự Postman Collections, với các tính năng tự động hóa nâng cao.Tính năng#
Truyền dữ liệu giữa các yêu cầu. Khả năng nâng cao#
Báo cáo kiểm thử và kiểm thử hiệu năng.
Kiểm thử dựa trên dữ liệu.
Kịch bản kiểm thử tự động đồng bộ với các thay đổi của đặc tả API, đảm bảo kiểm thử vẫn hợp lệ khi API phát triển.
Chế độ Design-first & Chế độ Request-first#
Module API của Apidog có hai chế độ có thể chuyển đổi ở góc dưới bên trái của giao diện: Design-first Mode và Request-first Mode.Cả hai chế độ đều cung cấp các chức năng tương tự nhưng có giao diện khác nhau, phù hợp với các quy trình làm việc khác nhau của nhóm.Chế độ Design-first#
Được khuyến nghị cho các nhóm thực hành thiết kế API trước.
Định nghĩa đặc tả API trước khi phát triển và kiểm thử.
Lý tưởng cho các dự án có kế hoạch và được dẫn dắt bởi đặc tả.
Chế độ Request-first#
Phù hợp với các nhóm tập trung vào phát triển backend trước.
T ạo yêu cầu, sau đó tạo đặc tả từ các lệnh gọi thành công.
Hoàn hảo cho các API chưa được lập tài liệu hoặc tích hợp bên thứ ba.
Tóm tắt#
Việc hiểu các khái niệm cốt lõi này sẽ giúp bạn tận dụng cách tiếp cận API-first của Apidog để thiết kế, kiểm thử và cộng tác hiệu quả. Hãy bắt đầu bằng cách tạo một dự án, tổ chức endpoint thành các module, định nghĩa môi trường cho các giai đoạn khác nhau và xây dựng kịch bản kiểm thử để tự động hóa.Để đọc thêm, hãy khám phá các trang tài liệu được liên kết hoặc thử giao diện của Apidog để thấy các khái niệm này trong thực tế.
Sẵn sàng bắt đầu?#
Bắt đầu từ đầu
Bắt đầu với Apidog từ đầuDi chuyển sang Apidog
Bắt đầu bằng cách di chuyển sang Apidog 