YApi: Nền tảng quản lý API tự triển khai

Vì sao đội ngũ cần một nền tảng quản lý API riêng

Khi một API có nhiều hơn vài endpoint, ba nhóm người cần cùng một thông tin nhưng ở ba định dạng khác nhau: backend biết chính xác response thật trông ra sao, frontend cần một bản giả của response đó trước khi endpoint hoàn thành, còn QA cần một định nghĩa đủ chính xác để viết assertion. Một tài liệu chia sẻ hay một đống collection Postman gửi qua lại trong group chat sẽ lệch pha chỉ sau một sprint, và không ai nhận ra cho tới khi request lỗi ở staging. Cách YApi giải quyết là biến định nghĩa interface thành artifact duy nhất mà cả ba nhóm cùng đọc và ghi, với mock server và bộ chạy test được xây trực tiếp trên chính định nghĩa đó thay vì là công cụ tách rời phải đồng bộ thủ công.

YApi là gì

YApi là nền tảng quản lý API trực quan, tự triển khai, do đội YMFE xây dựng để kết nối frontend, backend và QA quanh một định nghĩa interface dùng chung. Mỗi API có một trang mô tả request/response bằng Json5, một debug console kiểu Postman, và một mock endpoint sinh từ chính định nghĩa đó qua Mock.js. Bạn chạy YApi trên hạ tầng của mình, dùng MongoDB, nên dữ liệu interface không rời khỏi mạng nội bộ.

Tính năng cốt lõi của YApi

• ✓Cấu trúc response và tài liệu được định nghĩa một lần bằng Json5, và cả mock endpoint lẫn trang tài liệu đều đọc từ đúng định nghĩa đó.
• ✓MockServer hỗ trợ mock ngẫu nhiên thông thường lẫn chế độ 'mock expectation' — khớp theo rule lọc request cụ thể và trả về đúng response kỳ vọng cho từng rule.
• ✓Debug console kiểu Postman tích hợp sẵn để gọi endpoint và xem response mà không cần rời khỏi YApi.
• ✓Test tự động kèm assertion trên response, để một hợp đồng API bị vỡ có thể chặn lại ở bước kiểm tra thay vì lộ ra tận frontend.
• ✓Import dữ liệu từ collection Postman, file HAR và dữ liệu Swagger, nên một collection có sẵn không cần dựng lại từ đầu.
• ✓Mô hình phân quyền phẳng mà README mô tả là vẫn đáp ứng được các dự án lớn, nhiều team, trong khi vẫn dễ dùng cho dự án nhỏ.
• ✓Chạy hoàn toàn trong mạng nội bộ của bạn, nên dữ liệu interface không chạm tới server bên thứ ba.
• ✓Hệ sinh thái plugin cộng đồng gồm đăng nhập SSO, CAS, OAuth2, đồng bộ GitLab và thông báo qua bot DingTalk, do các contributor bên ngoài xây dựng.

Triển khai YApi bằng yapi-cli

Việc triển khai đi qua chính CLI của YApi. Cài đặt bằng `npm install -g yapi-cli --registry https://registry.npm.taobao.org` — lưu ý flag registry trỏ tới mirror npm của Taobao, đúng như lệnh trong README, nên kiểm tra mirror này có truy cập được từ mạng của bạn trước khi phụ thuộc vào nó. Chạy `yapi server` sẽ mở một trình cài đặt trực quan: điền cấu hình, bấm qua các bước deploy, và nó sẽ tạo ra site. Khởi động server bằng `node {đường-dẫn-site}/server/app.js`, sau đó mở site trên trình duyệt và đăng nhập bằng email admin đã đặt lúc cài — mật khẩu mặc định là `ymfe.org`, có thể đổi sau đó trong trang cá nhân. Yêu cầu hệ thống gồm Node.js 7.6+, MongoDB 2.6+ và git trên máy chủ. Để quản lý tiến trình, cài pm2 toàn cục rồi chạy `pm2 start "vendors/server/app.js" --name yapi`, cùng với `pm2 info yapi`, `pm2 stop yapi`, `pm2 restart yapi` cho việc vận hành hằng ngày. Nâng cấp cũng đi qua cùng CLI: `yapi ls` liệt kê các phiên bản, `yapi update` cập nhật lên bản mới nhất, và `yapi update -v {version}` để chỉ định phiên bản cụ thể; README nói rằng nâng cấp chỉ đồng bộ lại thư mục vendors và không đụng tới dữ liệu project đã có. README cũng dẫn tới vài cách triển khai Docker và docker-compose không chính thức nếu bạn muốn container hoá, dù không cái nào do team gốc bảo trì.

Lựa chọn thay thế YApi

Câu hỏi thường gặp

Trường hợp sử dụng tốt nhất

• •Giữ một hợp đồng interface duy nhất mà frontend, backend và QA cùng đọc trong suốt quá trình phát triển tính năng.
• •Mock một API phụ thuộc trước khi endpoint backend thật tồn tại, để công việc frontend không bị chặn lại vì thứ tự làm backend.
• •Chạy assertion tự động trên response như một bước kiểm tra hồi quy khi hợp đồng API thay đổi.
• •Chuyển một collection Postman hoặc Swagger có sẵn vào một hub tài liệu dùng chung, được host nội bộ.
• •Các tổ chức lớn cần một mô hình phân quyền đủ linh hoạt cho nhiều team, nhiều dự án, nhưng vẫn đơn giản để không cần một admin chuyên trách.

Ai nên dùng — và ai nên bỏ qua

Nên thử YApi nếu team của bạn có frontend, backend và QA thực sự cần dùng chung một định nghĩa interface, và bạn không ngại tự vận hành một service Node.js kèm MongoDB — tính năng mock expectation đặc biệt đáng giá khi QA viết kịch bản test thật thay vì chỉ nhìn qua loa dữ liệu JSON ngẫu nhiên. Bỏ qua nếu bạn không muốn sở hữu một service tự triển khai, hoặc nếu bạn chỉ là một developer làm việc một mình, khi đó một công cụ nhẹ hơn như json-server có thể đáp ứng nhu cầu mock mà không cần setup phức tạp.

Repo liên quan