Swagger là gì? Hướng dẫn cách cài đặt Swagger đơn giản

Vinh Phạm

1175

31-03-2022

Swagger có lẽ là một thuật ngữ quá quen thuộc với dân công nghệ thông tin. Tuy nhiên để có thể công cụ này một cách tốt nhất trong lĩnh vực, công việc của mình, những nhà lập trình viên cần phải hiểu rõ ý nghĩa cũng như lợi ích mà Swagger mang lại. 

Bài viết dưới đây Bizfly Cloud sẽ giúp bạn giải đáp về khái niệm, cấu trúc và các bước để có thể cài đặt được công cụ Swagger.

Khái niệm về Swagger

Swagger là bộ công cụ mã nguồn mở, được dùng để xây dựng nên Open API Specifications. Đây là công cụ giúp đơn giản các thiết kế, tạo dựng các tài liệu cũng như việc sử dụng Rest APIs.

Các nhà phát triển khi sử dụng Swagger sẽ được cung cấp đầy đủ ba loại tool như sau:

• Tool Swagger Editor: Tool này được sử dụng với mục đích thiết kế và xây dựng nên các APIs mới hoàn toàn hoặc edit lại những APIs có sẵn bằng cách tận dụng một file config.
• Tool Swagger Codegen: Thông qua việc sử dụng các file config có sẵn trước đó, Swagger Codegen có thể generate (tạo ra) code.
• Tool Swagger UI: Xuất phát từ một file config, Swagger UI được ứng dụng trong việc generate các file thành CSS, HTML,...

Để thực hiện việc viết document cho Swagger thì các nhà phát triển có thể tiếp cận với bộ mã nguồn này thông qua hai cách sau:

• Cách 1: Top down approach: Thiết kế các APIs trước khi thực hiện việc code liên quan.
• Cách 2: Bottom down approach: Thông qua việc sử dụng những thiết kế có sẵn của file config để thực hiện mô tả các vấn đề cũng như thông số liên quan đến API.

Cấu trúc của Swagger

Swagger bao gồm 4 cấu trúc cơ bản:

- Metadata hay Info: Hỗ trợ đưa ra các từ khóa về các thông tin liên quan như: thông tin liên lạc, thông tin chứng chỉ, các điều khoản trong việc sử dụng. Phần info sẽ có các thông tin cơ bản về API như title, description và các version. Cụ thể như sau:

• Title: tên của AP
• Description: Đưa ra chi tiết thông tin về API
• Version: Được sử dụng trong trong quá trình tạo dựng của người sử dụng với API

- Servers: Thực hiện chức năng test các API. Việc định nghĩa một hay nhiều servers khác nhau sẽ hoàn toàn tùy thuộc vào quyết định của người dùng.

- Paths: Đây là phần mấu chốt, trọng tâm của API . Người dùng cần định nghĩa những paths xuất hiện trong API hoặc các phương thức những tham số cụ thể mà API đó bao gồm.

- Schema: Được định nghĩa như một model. Thông qua việc sử dụng các từ khóa component và schemas, Schema sẽ được thực hiện phần khai báo

(Lưu ý: Với những chỗ gọi đến schema, bạn bắt buộc phải chỉ định chính xác đường dẫn)

Việc tìm hiểu kỹ càng cấu trúc cơ bản của Swagger sẽ giúp các lập trình viên có thể hiểu rõ hơn về Swagger cũng như có được những cách sử dụng Swagger thích hợp nhất cho từng trường hợp cụ thể.

Swagger hỗ trợ API như thế nào?

Swagger giữ vai trò quan trọng rất lớn trong việc hỗ trợ API. Cụ thể,

• Công cụ Swagger có ứng dụng rất lớn trong việc xây dựng giao diện cho các tài liệu bắt nguồn từ file config áp dụng dưới chuẩn của Ipen API. Các nhà phát triển có thấy rõ được tính tường minh, rõ ràng và cụ thể khư sử dụng công cụ này.
• Mỗi API được sử dụng sẽ cho các nhà lập trình viên biết một cách chính xác nhất, chi tiết nhất về nguồn ra và nguồn vào. Thêm vào đó, các nhà lập trình viên cũng có thể dễ dàng đưa các dữ liệu vào trong để test thử độ chính xác của kết quả cũng như đảm bảo tính đúng đắn
• Swagger là một công cụ hữu ích hỗ trợ kiểm tra hồi quy sau những thay đổi lớn về mã. Công cụ này giúp ích rất nhiều cho API trong mô phỏng các trường hợp như điều kiện giao thông cao điểm hay tương tác với dữ liệu nước ngoài, tạo kiểm tra tải và kiểm tra API tự động.

Hướng dẫn cài đặt Swagger đơn giản

Để cài đặt Swagger, người dùng có thể thực hiện theo 3 bước dưới đây:

- Bước 1: Tiến hành thực hiện việc tải thư viện của Swagger

• Clone dự án Github
• Copy thư mục dist xuất hiện trong dự án Github vừa đc clone về
• Paste vào dự án sau đó lựa chọn render file index.html có trong dist

- Bước 2: Tạo config ở trong các cấu hình APIs

• Ngoài việc sử dụng yaml để viết các config, người dùng cũng có thể viết config dưới dạng Jsol. Tuy nhiên, tốt nhất nên viết ở định dạng yaml
• Tạo một file yaml với cấu trúc giống như trong Swagger đã có ở trước đó.
• Cuối cùng chỉ cần lưu lại tệp vừa tạo vào trong thư mục dist ở bước 1.

- Bước 3: Thực hiện việc cập nhật lại đường dẫn trong file config

• Trước tiên bạn cần mở file Index.html có trong dist,
• Tìm Swagger UI Bundle và thực hiện việc sửa path url thành đường dẫn đã được tạo trước đó
• Lưu lại rồi chạy server và truy cập lại vào router đã được nói đến ở bước 1.

Với tần suất sử dụng cũng như ứng dụng phổ biến của Swagger UI nhờ những chức năng phù hợp và thích hợp với các API, việc nắm rõ các bước cài đặt Swagger UI là điều cần thiết mà bạn cần thiết phải thực hiện.

Với Swagger, việc thiết kế và xây dựng các tài liệu của bạn sẽ trở nên đơn giản hơn, doanh nghiệp sẽ nhận được nhiều lợi ích hơn. Mong rằng, với những thông tin mà Bizfly Cloud mang lại, bạn sẽ hiểu rõ Swagger là gì, lợi ích mà nó mang lại cũng như sử dụng công cụ trên một cách hiệu quả nhất trong công việc của mình.