Swagger là gì? Tìm hiểu ứng dụng của Swagger trong thiết kế API

Cần tìm việc làm

1. Khái quát thông tin về OpenAPI

Tài liệu hướng dẫn sử dụng API chứa toàn bộ những nội dung kỹ thuật, yêu cầu chi tiết để làm có thể sử dụng API. Trong đó là những nội dung chi tiết về các phương thức, yêu cầu và phản hồi, tài nguyên và thông tin xác thực. Để tạo API thì cực cân giản như soạn thảo các văn bản thông thường. Để quá trình xử lý dữ liệu trong API được mượt mà và dễ bảo trì hơn thì cần đến sự hỗ trợ của các định dạng như OpenAPI và Swagger Specification. 

Open API dành cho REST APIS là một định dạng mô tả thuộc API. Thông qua một file OpenAPI thì người dùng có thể mô tả API về:

- Cách thức hoạt động của endpoint như DELETE, POST, GET, PUT và đồng thời cho phép chúng hoạt động (/users).

- Thể hiện các chỉ số đầu vào và ra của từng dữ liệu trong API

- Xác định được phương thức được sử dụng trong API với mục đích xác thực.

- Cho phép người dùng thấy được những thông tin liên hệ, điều khoản sử dụng và địa chỉ (HTTP/HTTPS).

API specifications được thiết kế dễ đọc hiểu bằng ngôn ngữ JSON hoặc YAML hỗ trợ tối ưu cho cả người dùng và cả ngôn ngữ máy tính. 

>> Xem thêm: Việc làm lập trình viên

2. Khái quát thông tin về Swagger

Swagger là gì? Swagger là một ứng dụng mã nguồn mở hỗ trợ OpenAPI specifications hỗ trợ người dùng để phát triển, thiết kế và xây dựng tài liệu được sử dụng cho các REST APIs cụ thể là RESTful Web Service. 

Ứng dụng Swagger cung cấp nhiều phần mềm với tinh năng riêng biệt như Swagger Codegen, Swagger Editor, Swagger UI và Swagger Inspector. Trong đó thì có 3 phần mềm chính mà được các nhà phát triển sử đó là Swagger Editor (tính năng thiết cho cả các APIs mới và có sẵn thông qua 1 file config), Swagger Codegen ( tạo ra các code từ những file có sẵn) và Swagger UI (tạo ra các định dạng file từ config như html, css,...).

Có 2 cách chính để viết document cho Swagger đó là Top-down approach và Bottom-up approach được dùng để mô tả API từ những file thiết kế mới hoặc có sẵn.

Trong số các phần mềm hỗ trợ nêu trên thì dân công nghệ thông tin sử dụng Swagger UI là nhiều nhất vì tính năng thiết kế giao diện cho tài liệu chuẩn OpenAPI từ những file config. Giao diện được thiết kế rõ ràng rành mạch dễ sử dụng và đọc hiểu cho cả người dùng thông thường. 

Xem thêm: Perl là gì? Vì sao Perl lại được ưa chuộng trong giới lập trình?

3. Những cấu trúc cơ bản của Swagger 

3.1. Metadata/Info

Để khai báo phiên bản thì mỗi một OpenAPI specifications sẽ được được đặt tên với từ khóa openapi ở đầu (ví dụ cụ thể openapi: 3.0.0). Ý nghĩa của việc đặt tên như vậy để phân biệt các phiên bản đồng thời giới thiệu toàn bộ cấu trúc của API Phân Info cung cấp toàn bộ những thông tin của API như tên (title), tùy chọn (description) và phiên bản (version). Trong đó:

- Title là tên gọi được cài đặt cho API

- Description là khái quát thông tin mô tả về API mang tính chất mở rộng, cho phép người dùng viết thành nhiều dòng và sử dụng cú pháp hỗ trợ Markdown.  

- Info là toàn bộ những thông tin liên hệ, địa chỉ (HTTP/HTTPS), điều khoản sử dụng cùng những thông tin liên quan khác.

- Version là phiên bản cài đặt của ứng dụng API.

Xem thêm: Middleware là gì? Những kiến thức cơ bản về phần mềm Middleware

3.2. Servers 

Cấu trúc này cho phép người dùng test API thông qua những đường dẫn được chỉ định của server. Người dùng có thể sử dụng cấu trúc này để có thể định nghĩa một hoặc nhiều server khác nhau thì khi đó đường dẫn tương đối của URL mà cần định nghĩa sẽ là những đường dẫn API.

cv online đẹp

3.3. Paths 

Paths là cấu trúc trọng điểm của API, tại cấu trúc này người dùng sẽ định nghĩa các paths trong tập tài liệu hướng dẫn API kèm theo đó là những thương thức và tham số cụ thể trong tập tài liệu đó. 

Khi sử dụng cấu trúc này người dùng cần phải để ý đó là:

- Những định nghĩa được sử dụng trong API trong phần cấu trúc này phải bắt đầu bằng từ PATHS.

 - Đằng sau từ khóa sẽ là những thành phần chi tên như là /user/{userld}) 

- Sau khi hoàn thành quá trình đặt tên thì bắt đầu lựa chọn những phương thức trong API như DELETE, GET, PUT, POST,...

- Phần mô tả ngắn tóm tắt nội dung trong API được gọi là summary

- Định nghĩa về parameters trong Paths là ám chỉ những tham số được đưa vào bên trong API. Người dùng được quyền cài đặt thêm những tham số required, đồng thời có thể mô tả chi tiết hoặc validate nó. Hơn nữa, người dùng có thể yêu cầu 1 schema (có thể hiểu là một model) hỗ trợ định nghĩa cho những chỉ số này thống qua schema & $ref.

- Sau khi thực hiện này thì sẽ có những phản hồi được đưa về máy chủ server. Người dùng có thể mô tả cho từng định nghĩa cho những code HTTP như 200, 404, 500,..

Trong các parameters có thể được khai báo các loại khác nhau thông qua những định dạng có kèm theo từ khóa “in”, tuy nhiên cần phải lưu ý một số điều như sau:

- In formData: hỗ trợ người dùng cài đặt input đã định trước để thực hiện đưa dữ liệu theo yêu cầu vào những miền định sẵn.

- In body: hỗ trợ tạo không gian cho người dùng nhập dữ liệu đầu vào, cho phép nhập mọi dữ liệu và những thao tác cơ bản bên trong.

- In path: có tính năng thành lập một input với mục đích đưa vào trong giá trị phục vụ khai báo cho các ID hay còn gọi là routers.

- In header: có nhiệm vụ khai báo toàn bộ những giá trị chứa trong header được yêu cầu bởi người dùng muốn truyền tải.

- In query: có nhiệm vụ thiết ra ra input để nhập vào những giá trị thống kê theo yêu cầu từng miền được định sẵn khi muốn thực hiện các query request.

4. Hướng dẫn cài đặt Swagger UI

Trong các cấu trúc cơ bản của Swagger thì Swagger UI được sử dụng phổ biến, với tính năng tạo ra các định dạng file từ config như html, css,... và thiết kế thân thiện tương hợp với API. Để cài đặt phần mềm Swagger UI cần thực hiện những bước sau đây:

- Bước 1: Đầu tiên cần thực hiện thao tác download thư viện của Swagger UI. Người dùng cần phải tải clone dự án Github, sau đó là copy những thư mục dist bên trong dự án đưa vào dự án của bạn, chọn render file index.html trong thư mục dist. Để nhận demo của Swagger UI nhấn chạy localhost:3000 trên trình duyệt.

- Bước 2: Tiến hành tạo file config trong chương trình APIs. 

Bên trong Swagger file yaml được thiết kế theo cấu trúc Open API, Info, Version, Title, Description, Component, Paths. Bên cạnh file yaml thì Swagger cho phép người dùng sử dụng file config được viết dưới dạng JSON nhưng khi sử dụng file yaml thì chức năng sẽ được tối ưu hơn. Dùng phần mềm Swagger UI bản demo vừa cài đặt tạo file là có thể thiết lập file mô tả thông tin về APIs và lưu bản đó vào thư mục dist tạo từ bước 1.

- Bước 3: Tiến hành reload lại đường link của file config. 

Người dùng chỉ cần dùng file index.html trong dist đã tạo, tiến hành sửa path URl trong Swagger UI Bundle sang đường link đã tạo bên trên, lưu lại và tiến hành chạy máy chủ server truy cập vào router ở bước 1 là xong. 

Bên trên là toàn bộ những thông tin cơ bản về Swagger và cách cài đặt Swagger UI cực kỳ đơn giản. Để tìm hiểu thêm những thông tin về ngành công nghệ thông tin truy cập website viecday365.com