Chào mọi người, tôi là Allie đến từ bộ phận Director Office của Money Forward Vietnam (MFV) - Chi nhánh Hà Nội.

Trong blog hôm nay, tôi sẽ giới thiệu đến mọi người một bài viết rất thú vị của bác Yoshioka, thuộc Phòng CTO ở MF Nhật Bản.

Tại MF Nhật, Phòng CTO là nơi đề xuất và tiếp nhận các ý tưởng để giải quyết những vấn đề kỹ thuật của toàn công ty, và thẩm định các công nghệ để đạt đến sự cải thiện của các giá trị bị gián đoạn.

Có nhiều ban nằm dưới Phòng CTO, và bác Yoshioka thuộc về Ban Xúc tiến Microservice (Microservices Promotion Department - MPD), nơi gánh vác mọi thứ từ ứng dụng đến cơ sở hạ tầng, xây dựng những microservice chung có thể áp dụng trong nhiều sản phẩm (product) của MF.

Bài viết hôm nay sẽ là về kinh nghiệm của bác tại ban MPD.

Bài viết được dịch dưới sự cho phép của tác giả.

---

“Phải chăng đây là một service ở cấp vi mô"?

Chào bạn đọc, tôi là Yoshioka, một server-side engineer của ban MPD thuộc Phòng CTO của MF.

Cái tên nói lên tất cả, MPD đảm nhận việc phát triển, vận hành và xúc tiến microservice mỗi ngày.

Các microservice chúng tôi đang phát triển thì không có liên hệ trực tiếp với người dùng cuối (end user) đâu, nhưng là thứ cung cấp hầu hết tính năng cho sản phẩm của MF.

Thường thì những chức năng đó sẽ được cung cấp thông qua RESTful API. Nhưng bằng cách tạo ra các specs (documentation) rõ ràng và dễ hiểu, chúng ta có thể đẩy mạnh sự cộng tác của các team hiệu quả hơn.

Vậy trong blog này, tôi sẽ giới thiệu “Làm sao để mang API specs đến cho những service đã được phát triển?”

Swagger là gì?

Nói cho gọn thì MPD dùng Swagger để tạo ra các tài liệu về API, mô tả các đặc tính kỹ thuật, cách sử dụng của các service, và cung cấp cho các sản phẩm trong công ty.

Tôi chắc chắn bạn có thể tìm thấy những lời giải thích rất rõ ràng và dễ hiểu về Swagger ngay tại trang chủ của họ. Nhưng nói ngắn gọn ở đây thi, Swagger là một framework hữu dụng để tạo ra các tài liệu cho API một cách tự động từ những dòng comment/ghi chú trong code.

Mặc dù Swagger có những chỉ dẫn rất rõ ràng về cách thiết kế REST APIs, nhưng trong bài viết này, tôi sẽ chỉ đề cập đến nó như là một công cụ để tạo ra tài liệu cho API, mà cụ thể ở đây là Swagger-Codegen và Swagger-UI.

Tại sao lại là Swagger?

Chắc hẳn là các bạn có rất nhiều cơ hội để viết tài liệu về kỹ thuật, nhưng bạn viết càng nhiều, thì việc quản lý nó sẽ càng khó, ví dụ:

Quá nhiều tài liệu về các API
Luôn phải cập nhật chúng với những thay đổi mới nhất
Phải đảm bảo chúng ta đã viết tài liệu ngay từ lúc đầu
...

Với Swagger, chúng ta không cần phải viết tài liệu một cách riêng biệt với code, mà có thể quản lý và cập nhật liên tục từ code đến tài liệu.

Khi bạn code để tạo ra một Request Path với những tham số theo một định dạng đã được định sẵn, tài liệu của API đó (dưới dạng JSON hoặc YAML file) sẽ được tạo ra một cách tự động dựa trên những mô tả về Request (ngay bên trong code), chỉ với một dòng lệnh (mặc dù nó không có nghĩa là bạn không cần phải viết tài liệu...).

Tài liệu được sinh ra bởi Swagger sẽ được hiển thị bởi Swagger UI (một công cụ khác để trực quan hoá các API với một giao diện rất đẹp)

Mặc dù còn nhiều tính năng khác mà Swagger mang đến nữa, nhưng đội ngũ MPD cũng đã quyết định sử dụng Swagger để quản lý các bản phát triển và tài liệu về API chung với nhau.

Mô phỏng chạy code từ phòng MPD

Tôi sẽ nói ngắn gọn cách tạo và publish tài liệu của các API.

Tạo document API

Trước khi tạo document, cần phải chú thích (annotate, comment) dòng code với đường dẫn (path), thông số (parameter) của RESTfulAPI và response model.

(Do đội ngũ Microservice phát triển các service bằng ngôn ngữ Golang nên chúng tôi dùng thư viện swaggo/swag để tạo document API).

Tiếp theo, cho chạy câu lệnh tạo ra từ command line.

Chỉ ngắn gọn vậy thôi, rất đơn giản.

Publish tài liệu API (cho nội bộ sử dụng)

Đối với Phòng MPD, có hai cách để publish document API trong nội bộ.

Đẩy lên github
Chuẩn bị một môi trường công cộng trong để deploy microservice và cung cấp Swagger-UI

Cách 1: để mọi người tham khảo document (tài liệu) API trên github thông qua trình duyệt web. Bạn chỉ việc upload document API lên Github, vậy là các Dev có thể dễ dàng publish API specs rồi.

Tuy nhiên, vì tài liệu API chỉ là các tệp JSON / YAML, nên người xem cần phải cài đặt các tiện ích mở rộng như swagger-viewer.

Cách 2: để publish Swagger-UI dưới dạng 1 URL trong môi trường deploy. Miễn là người xem biết URL để đến trang đích, họ có thể xem model API được trực quan hoá trong Swagger-UI như hình bên dưới.

Những điểm chúng tôi sẽ cải thiện trong tương lai

Tự động khởi tạo/cập nhật document

Hiện tại, để tạo hay cập nhật tài liệu API, các Dev phải chạy câu lệnh để khởi tạo, sau đó commit/push file đã được tạo ra.

Vì các câu lệnh được khởi tạo hầu như đã cố định, chúng tôi muốn thêm vào một cơ chế để các tài liệu API tự tái khởi tạo khi có một sự thay đổi trong API specs.

Gửi Request từ Swagger-UI

Trên giao diện Swagger-UI, bạn có thể tạo HTTP Request và gửi đi.

Khá thuận tiện khi cần kiểm tra hành vi API và hiểu được nó vận hành ra sao, nhưng nó đòi hỏi sự xác thực trong môi trường Staging và Dev, thứ chúng tôi vẫn chưa hoàn thiện, nhưng bạn có thể bỏ qua giai đoạn xác thực bằng cách set up đúng.

Vì chúng tôi đang sử dụng Swagger-UI, chúng tôi sẽ review cấu hình (configuration) để mà chúng tôi có thể sử dụng tính năng này thật sự hữu hiệu.

Tóm lại

Trên đây tôi đã giới thiệu về API specs và cách dùng Swagger trong phòng MPD.

Mặc dù còn khá nhiều thứ chúng tôi chưa tận dụng hoàn toàn, nhưng chúng tôi sẽ tiếp tục sử dụng các công cụ bên ngoài và áp dụng tự động hoá để giảm thiểu những công việc rườm rà và dành nhiều thời gian hơn để phát triển service của chúng tôi.

Bên cạnh việc phát triển microservice, phòng MPD cũng đang chuyên tâm vào tự động hoá các task bằng các tool “nhà làm" hoặc Github Actions bên cạnh Swagger.