Bàn về hai công cụ tạo tài liệu cho API là Postman và Swagger

Vấn đề

Là một lập trình viên thì phải viết mã, điều đó không cần phải bàn cãi. Ngoài việc ngồi hàng giờ gõ những dòng logic ra thì còn rất nhiều công việc khác mà chúng ta cần phải làm nữa. Trong đó, việc gần như không thể tách rời là thêm tài liệu cho những gì mà mình viết ra.

Khi còn ngồi trên ghế nhà trường, Kiến trúc phần mềm là một môn không thể thiếu đối với sinh viên chuyên ngành về lập trình phần mềm ứng dụng. Chúng ta được học rất nhiều mô hình, biểu đồ cho đến cả quy trình để phát triển ứng dụng. Các khái niệm đó thi thoảng vẫn được nhắc lại trong môi trường làm việc, như waterfall, agile scrum... hay là các bản vẽ về biểu đồ hoạt động, tuần tự... của một chức năng nào đó.

Thú thật, đã từng có khoảng thời gian tôi rất ghét công việc viết tài liệu này, thậm chí còn cho rằng nó đang phí phạm quá nhiều thời gian không cần thiết. Thay vì ngồi vẽ biểu đồ, viết tài liệu... thì những logic thượng thừa nghĩ ra trong khi code vẫn là cái gì đó đáng để dành thời gian hơn rất nhiều.

Từ khi ra trường, xây dựng một hệ thống API gần như là nhiệm vụ xuyên suốt phải làm. Tôi có thể tạo ra hàng trăm CURD với các thông số từ đơn giản đến phức tạp, "truyền bá" chúng đến với các anh chị em đồng nghiệp bằng cách gửi thẳng qua những dòng tin nhắn, hoặc là đôi khi "note" nó vào ghi chú, "chuyên nghiệp" hơn thì gửi hẳn một liên kết đến Postman - nơi có chứa các bản mẫu của API đã tạo ra. Nhưng dù là cách gì đi chăng nữa thì cũng chỉ là giải pháp truyền đạt thông tin một cách tạm thời.

Gieo gió thì có ngày gặt bão, quả báo đến không lâu sau đó, khi thi thoảng lại bị lụt trong một mớ câu hỏi về dữ liệu đầu vào, và cả ý nghĩa của từng trường dữ liệu mà tôi tạo ra. Ái chà! Có phải tính năng này mình làm ra hay là không đây, sao mà cái gì cũng lạ lẫm thế này, tại sao lại yêu cầu cái này nhỉ, cái kia để làm gì không biết!!!

Đấy là nói đùa thế chứ sự việc cũng không đến mức nghiêm trọng như bạn nghĩ 😅. Qua thời gian ai rồi cũng phải lớn, việc tiếp xúc và học thêm được nhiều điều từ những người đi trước giúp cho mình biết thêm được nhiều tí. À hoá ra là cũng có cả một chuẩn hoá về việc xây dựng tài liệu cho hệ thống API, mà thường hay gặp nhất là Postman Collections và Swagger.

Postman

Postman chắc không cần phải giới thiệu gì nhiều rồi. Một phần mềm kinh điển mà tôi tin rằng gần hết lập trình viên đều biết. Nghe đâu khởi đầu của nó là phần mềm dùng trong việc kiểm thử API. Sau này phát triển dần dần lên thành một nền tảng API cho các nhà phát triển thiết kế, xây dựng, thử nghiệm và cộng tác làm việc trên các API.

Hay nói ngắn gọn nó là một trình gọi API.

Một khái niệm cơ bản của Postman là Collections. Tập hợp các endpoints tạo thành một Collections. Thông thường lập trình viên tạo thêm các endpoints vào Collections, lưu lại để sử dụng lại trong khoảng thời gian sau đó. Hoặc chia sẻ cho nhau cùng sử dụng. Có một điều thú vị là từ Collections, bạn có thể xuất bản thành một trang tài liệu API hoàn chỉnh.

Hãy nhìn vào một ví dụ về API của Cloudflare tại Cloudflare Client API v4, có thể thấy danh sách đầy đủ các endpoints kèm theo những thông số cần thiết trong body và headers. Nó trông chuyên nghiệp hơn nhiều so với cách viết vào ghi chú trước đây.

Tạo một tài liệu API bằng Collections rất đơn giản. Sau khi tạo xong Collections, thêm vào các endpoints, chuột phải vào tên, chọn "View documentation", tại đây sẽ thấy bản xem trước của trang tài liệu. Nếu muốn xuất bản nội dung lên Internet, bấm vào "Publish" ở phía trên bên tay phải, một cửa sổ web mở ra với các thông số thiết lập trước khi sẵn sàng publish. Cuối cùng bấm vào Publish để hoàn tất.

Bạn cũng có thể thêm mô tả (description) vào từng endpoints để bổ sung thông thêm tin chi tiết. Trong mỗi màn thêm endpoint, bấm vào ô "Documentation" và nhập vào mô tả, các thông tin này cũng đồng thời xuất hiện trong trang Publish của tài liệu.

Nhìn chung cách viết tài liệu bằng Postman Collections này tương đối dễ dàng và nhanh chóng. Tuy nhiên vẫn có một vài hạn chế như không thể hiện được rõ kiểu của tham số, tham số nào là tuỳ chọn hay bắt buộc, và các yêu cầu phức tạp hơn như tạo tài liệu tự động từ trong mã... Những lúc như thế chúng ta cần một cái tên khác - Swagger.

Swagger

Swagger là một bộ công cụ mã nguồn mở được sử dụng để thiết kế, xây dựng, tài liệu hóa và sử dụng như một máy khách truy cập các dịch vụ của web RESTful. Swagger giúp các nhà phát triển API mô tả chính xác và nhất quán các dịch vụ của họ.

OpenAPI là một đặc tả kỹ thuật cho các API RESTful, được phát triển từ dự án Swagger. OpenAPI cho phép các nhà phát triển mô tả toàn bộ API của họ trong một tài liệu duy nhất (thường là ở định dạng YAML hoặc JSON).

Đây là một ví dụ của một trang tài liệu API được tạo thành từ tệp YAML Swagger Petstore. Một danh sách được phân loại rõ ràng kèm nhiều thông tin chi tiết cho mỗi endpoint. Swagger cũng đóng vai trò như là một API client khi nó cho phép chạy thử các đầu API ngay trên chính trang web.

Swagger bao gồm nhiều công cụ hỗ trợ tạo cấu trúc OpenAPI như là Swagger UI, Swagger Editor, Swagger Codegen... Trong đó UI và Editor là giao diện và trình soạn thảo, Codegen là công cụ tạo mã nguồn tự động, hỗ trợ hơn 40 ngôn ngữ lập trình.

Vì là một công cụ mạnh mẽ cho nên để bắt đầu với Swagger khá phức tạp. Cần dành thời gian nghiên cứu và tìm hiểu để ứng dụng được nó trong công cuộc tạo "documentation" cho API. Có hẳn một trang tài liệu hướng dẫn rất chi tiết từng bước sử dụng Swagger Editor để tạo cấu trúc cho OpenAPI tại OpenAPI Guide.

Một cách tiếp cận nhanh chóng hơn là hãy tham khảo trang tài liệu ví dự ở phía trên. Hãy nghiên cứu tệp YAML của nó để biết cách sao chép và thêm mới một endpoint ngay lập tức. Hãy nhớ hầu hết những thứ cần thiết để tạo tài liệu đều có trong Swagger, thế nên hãy sử dụng kỹ năng tìm kiếm để biết cách thêm chúng vào dự án.

Nhìn chung tất cả những gì bạn cần là một cấu trúc YAML chứa đặc tả của OpenAPI, sau đó đưa nội dung này vào trình Swagger UI, nó sẽ giúp hiển thị nội dung này giống như trong ví dụ đã đề cập phía trên bài viết.

Sau đó hãy thử bắt đầu nghiên cứu cách tạo tài liệu tự động bằng việc viết mã. Bạn biết nestjs chứ? Hãy xem họ hướng dẫn tạo tài liệu tự động như thế nào tại OpenAPI Introduction. Ngoài nest ra, còn nhiều thư viện/framework cũng hỗ trợ tạo cấu trúc OpenAPI này nữa.

Chuyển đổi

Chính vì sự phổ biến và hữu ích của Postman và Swagger mà có cách chuyển đổi hai định dạng này với nhau. Nghĩa là từ Collections sang OpenAPI và ngược lại, tuỳ sở thích của mỗi người.

postman-to-openapi là một ví dụ về công cụ chuyển đổi Collections sang OpenAPI. Còn phía ngược lại, Postman hỗ trợ sẵn tính năng nhập tệp YAML có cấu trúc của OpenAPI vào để tạo thành Collections Postman Supports OpenAPI 3.0. Thế cho nên chỉ cần vào Postman, chọn "Import" rồi tải lên tệp YAML của OpenAPI là hoàn thành.

Tổng kết

Trên đây là lời giới thiệu ngắn gọn về 2 công cụ trợ giúp tạo tài liệu API từ đơn giản đến phức tạp. Tuỳ vào từng trường hợp, nhu cầu mà có cách chọn sao cho hợp lý. Trong khi Postman rất đơn giản để bắt đầu thì Swagger lại cần một chút thời gian để học cách sử dụng.

Còn bạn đang sử dụng công cụ hoặc phương pháp nào để tài liệu hoá API? Hãy chia sẻ xuống dưới phần bình luận nhé. Xin cảm ơn!