Swagger là gì? Bạn hiểu gì về công cụ viết document cho API?

1. Bạn hiểu như thế nào về Swagger là gì?

Hiểu ý nghĩa của Swagger là gì để giúp bạn có thể ứng dụng công cụ này một cách tốt nhất cho công việc của mình.

Tuy nhiên, trước khi đi tìm hiểu định nghĩa của Swagger thì bạn cần biết Open API là gì và có mối tác động, liên hệ ra sao với Swagger.

1.1. Hiểu gì về Open API?

Open API được biết đến với tên đầy đủ là Open API Specification. Đây được biết đến là một loại định dạng dùng để mô tả API cho một Rest APIs hiện nay. Với duy nhất một file Open API, bạn sẽ có thể mô tả được toàn bộ API. Điều này có nghĩa là việc mô tả sẽ bao gồm cả những nội dung sau đây:

- Tạo điều kiện hoạt động các các endpoints hay là các users cũng như cách thức hoạt động của các endpoints đó như get/users, post/users.

- Hiển thị rõ được các tham số về đầu vào và đầu ra của mỗi hoạt động.

- Thể hiện các phương thức xác thực được sử dụng.

- Thể hiện các thông tin liên lạc, các chứng chỉ, những điều khoản liên quan đến việc sử dụng và các thông tin liên quan khác.

Thực tế thì API Specifications hiện có thể được viết bằng các định dạng như JSOL hay YAML. Đây được biết đến là hai định dạng có lợi cho cả người dùng và hệ thống máy tính khi rất dễ đọc, dễ hiểu để sử dụng.  

Tìm hiểu thêm: Spring Boot là gì?

1.2. Định nghĩa Swagger là gì?

Nếu như Open API có ý nghĩa quan trọng như trên thì điều gì đã tạo nên được bộ mô tả này? Và đó chính là Swagger. Swagger được hiểu là một công cụ có mã nguồn mở và dùng để xây dựng nên Open API Specifications. Công cụ này sẽ giúp bạn trong việc thiết kế, tạo dựng các tài liệu cũng như việc sử dụng Rest APIs.

Với các nhà phát triển, khi sử dụng Swagger sẽ được cung cấp 3 tool chính như sau: 

- Tool Swagger Editor: Được sử dụng để thiết kế, xây dựng nên các APIs một cách mới hoàn toàn hoặc là có thể edit lại từ những APIs có sẵn với việc tận dụng một file config.

- Tool Swagger Codegen: Có tác dụng trong việc generate ra code thông qua sử dụng các file config sẵn có trước đó.

- Tool Swagger UI: Ứng dụng trong việc generate các file ra HTML, CSS,...xuất phát từ một file config.

Để có thể thực hiện việc viết document cho Swagger thì các developers sẽ có 2 cách để tiếp cận với bộ mã nguồn mở này. 

- Cách 1: Top down approach: dùng để thiết kế nên các APIs trước khi thực hiện việc code liên quan.

- Cách 2: Bottom down approach: dùng để mô tả các vấn đề, thông số liên quan API thông qua việc sử dụng thiết kế có sẵn của file config.

Với những tool được liệt kê ở trên của Swagger thì Swagger UI được biết đến là một tool có sự thông dụng phổ biến nhất hiện nay. Với tool Swagger UI, tool này 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. Giao diện được tạo ra bởi tool này thường có tính tường minh và khá rõ ràng, hiện ra một cách cụ thể nhất cho các nhà phát triển. Điều này sẽ giúp ích rất lớn cho cả người dùng lẫn các lập trình viên trong việc đọc hiểu và sử dụng. Thêm vào đó, đây cũng là dẫn chứng có việc các developers sử dụng file config nhưng lại có sự tách biệt một cách hoàn toàn giữa các tác vụ với nhau.

Mỗi API được sử dụng trong quá trình này sẽ cho chúng ta biết một cách chính xác nhất về nguồn vào và nguồn ra một cách chi tiết. Thêm vào đó chính là việc những trường cần phải được gửi lên hệ thống cũng như các trạng thái kết quả có thể được trả về. Điều đặc biệt nhất có lẽ chính là việc ta có thể đưa các dữ liệu vào trong để test thử các kết quả liệu có thực sự chính xác và đảm bảo tính đúng đắn hay không. 

Tham khảo: Tuyển dụng việc làm lập trình viên

2. Những cấu trúc cơ bản của Swagger là gì?

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

2.1. Metadata hay Info

Hầu hết, mỗi Open API Specifications được sử dụng đều sẽ bắt đầu với từ khóa “Open API” nhằm mục đích cho việc khai báo tên của phiên bản đó. Với loại phiên bản được sử dụng sẽ có ý nghĩa trong việc định nghĩa lại toàn bộ những cấu trúc ở trong API. Phân info sẽ có các thông tin cơ bản về API như title, description và các version. Cụ thể thì:

- Title sẽ là tên mà bạn đặt cho API của mình.

- Description chính là các thông tin về API của bạn được đưa ra một cách chi tiết avf xuất hiện ở nhiều mặt cụ thể khác nhau. Với việc mô tả này thì bạn hoàn toàn có thể viết thành nhiều dòng nếu như quá dài và sử dụng cú pháp hỗ trợ như markdown.

- Version là phiên bản được sử dụng trong quá trình tạo dựng của bạn với API.

Metadata hay Info sẽ có chức năng trong việc 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 về chứng chỉ, các điều khoản trong việc sử dụng,...

2.2. Servers

Để có thể test được các API thì bạn cần có một đường dẫn liên quan đến servers. Và đây chính là phần tạo ra một đường dẫn cụ thể của servers được sử dụng để thực hiện chức năng trên. Trong phần này, việc định nghĩa một hay là nhiều các servers khác nhau sẽ hoàn toàn tùy thuộc vào quyết định của bạn.

Xem thêm: Front end là gì? Kỹ năng gì cho một Front end developer chuyên nghiệp?

2.3. Paths

Được biết phần mấu chốt, trọng tâm của API được sử dụng. Với phần này, nhiệm vụ của bạn và những nhà lập trình viên khác chính là định nghĩa những paths xuất hiện trong API hay các phương thức, những tham số cụ thể tồn tại trong API đó.

Một vài lưu ý trong phần này cần được chú ý như sau:

- Việc bắt đầu sẽ cần phải bằng từ khóa “paths”.

- Tiếp đó mới đến những thành phần có trong API như users,..

- Sau đó chính là các phương thức được sử dụng trong API như Get, Post, Delete,...

- Phần mô tả một cách tóm tắt, ngắn gọn của API: Summary

- Những tham số được đưa vào trong API gọi là parameters. Với phần này bạn có thể thực hiện việc set các tham số required, thực hiện việc mô tả những tham số đó hoặc là validate cho chúng. Thêm vào đó, điều đặc biệt ở phần này chính là việc bạn có thể chỉ định một model bất kỳ nhằm mục đích định nghĩa cho những tham số đó.

- Cuối cùng là phần trả về của server đó hay còn được biết đến là response. Với phần trả về này thì bạn có thể thực hiện việc định nghĩa cho các HTTP code mà người dùng có thể nhận được như 200, 404,... kèm theo đó là những dòng mô tả xuất hiện với từng trường hợp cụ thể.

Thêm vào đó, ở phần này, các parameters sẽ sở hữu khá nhiều loại khai báo khác nhau đứng sau từ khóa “in” mà chúng ta đều cần phải lưu ý:

- In body: Giúp cho người dùng có một không gian để tạo ra một dữ liệu đầu vào. Ở không gian này, người dùng hoàn toàn có thể nhập  các dữ liệu về những yêu cầu cơ bản vào trong đó.

- In formData: Giúp cho người dùng tạ được input đã được định trước để có thể thực hiện nhập các dữ liệu yêu cầu theo từng miền đã được định sẵn.

- In path: Sử dụng trong việc tạo lập một input vào trong giá trị để khai báo trong các routers, thông thường được gọi là ID. 

- In query: Được sử dụng trong việc tạo input nhập vào các giá trị thống kê theo các miền định sẵn để dùng trong việc gửi các query request.

- In header: Thực hiện việc dùng để khai báo các giá trị có trong header của yêu cầu mà bạn cần thực hiện truyền tải lên. 

2.4. Schema

Nói một cách dễ hiểu và đơn giản nhất thì Schema có thể được định nghĩa như một model. Schema sẽ được thực hiện phần khai báo thông qua việc sử dụng từ khóa component và schemas. 

Bài chi tiết: Schema là gì? Công dụng tuyệt vời của Schema

Những vấn đề cần quan tâm như:

- Loại tham số đầu tiên được sử dụng là tên của model hay users.

- Sau đó chính là định dạng được sử dụng hay object.

- Cuối cùng chính là các thông tin về thuộc tính.

3. Cài đặt Swagger UI như thế nào?

Như đã nói ở trên thì Swagger UI được biết đến là có tần suất sử dụng cũng như ứng dụng phổ biến nhất trong tất cả các loại Swagger hiện nay. Đây cũng là tool sở hữu những chức năng khá phù hợp và thích hợp trong các API.

Vậy, làm thế nào để cài đặt Swagger UI? Để cài đặt được tool này thì các bạn có thể thực hiện theo các bước sau:

- Bước 1: Thực hiện việc tải thư viện của Swagger UI

Đầu tiên, các bạn cần clone dự án Github về, tiếp đó thực hiện việc copy thư mục dist xuất hiện ở trong dự án đó. Paste vào dự án của bạn, sau đó lựa chọn render file index.html có trong dist. Đến đây, nếu như bạn chạy localhost:3000 ở trên trình duyệt thì bạn sẽ nhận được một trang demo của Swagger UI.

Thảm khảo thêm: Tư vấn việc làm công nghệ thông tin

- Bước 2: Thực hiện việc tạo config ở trong các cấu hình APIs

Thực tế thì ở trong một file yaml có trong Swagger sẽ có những cấu trúc như sau: Open API, Info, Title, Version, Description, Security, Paths, Component.

Bên cạnh những điều này thì sẽ có cả những keyword khác mà các bạn có thể sử dụng tại trang document của Swagger.

Ngoài yaml thì bạn cũng có thể viết các config ở dưới dạng Jsol với Swagger. Tuy nhiên, lời khuyên cho bạn chính là tốt nhất hãy nên viết ở định dạng yaml. Sau đó hãy tạo một file yaml của bạn với cấu trúc giống như trong Swagger UI demo đã có trước đó. Chỉ vài bước đơn giản là ta đã có thể có được một file config với đầy đủ các thông tin khá chi tiết về APIs. Tiếp đến chính là việc lưu lại tệp 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 của file config 

Để thực hiện việc cập nhật này bạn cần mở file có tên là index.html ở trong dist. Sau đó, tìm Swagger UI Bundle và thực hiện việc sửa path url thành đường dẫn mà bạn vừa tạo được trước đó. Tiếp đó bạn hãy lưu lại, rồi chạy server và truy cập lại vào router đã xuất hiện ở ngay bước 1.

Trên đây là những thông tin cơ bản về Swagger gửi tới các bạn. Hy vọng rằng, với những chia sẻ trên đây thì các bạn đã hiểu được Swagger là gì và ứng dụng của Swagger hiện nay.