Swagger API Development for Everyone

Đặt vấn đề

Trước khi đi vào khái niệm và tác dụng của Swagger. MEVN sẽ đặt một trường hợp để giúp bạn hiểu rõ hơn về Swagger.

Giả sử có hai nhóm đang thực hiện cùng một dự án. Và cả hai phải cùng chia sẻ thông tin, tài liệu cho nhau mới có thể hoàn thành được dự án. Vậy làm cách nào để giải quyết vấn đề này?

Hướng giải quyết thông thường

Vấn đề này thực sự rất đơn giản phải không? Chỉ một file document. File này sẽ đảm nhiệm việc lưu các thông tin tài liệu và chỉ một phát nhấp chuột là đã có những thông tin, tài liệu cần thiết.

Hướng giải quyết trong lập trình

Ngay cả trong lập trình, phương pháp này cũng được áp dụng. Khi cần truyền thông tin và dữ liệu cho nhau họ sẽ cần tạo APIs. Sau đó đưa các mô tả chi tiết của api vào một file document hay có cách gọi khác là file OpenAPI. Nhóm kia sẽ dựa vào các thông tin APIs trong file OpenAPI để nhận dữ liệu cần dùng.

Vậy câu hỏi được đặt ra làm thế nào để đối tác biết bạn đang cung cấp những tài nguyên gì, làm thế nào để lấy được tài nguyên đó và xem được những tài nguyên có đúng như nhu cầu của họ không? Vì thế công cụ Swagger được sinh ra.

Vậy Swagger là gì? Và nó giúp bạn giải quyết các vấn đề trên như thế nào?

Swagger là gì? Swagger là một bộ các công cụ open-source được xây dựng xung quanh OpenAPI Specification. OpenAPI Specification là một dạng mô tả chi tiết APIs cho REST APIs. Bạn có thể hiểu REST APIs là một tiêu chuẩn dùng trong việc thiết kế các thiết kế API cho các ứng dụng web. Khi dùng OpenAPI Specification tài liệu của bạn sẽ hiển thị ở định dạng gọn gàng, dễ đọc.

Để thuận tiện hơn cho bạn design, build, tạo document và dùng REST APIs Swagger đã chia thành các công cụ khác nhau:

• Swagger Editor – trình chỉnh sửa trên trình duyệt. Bạn có thể viết thông số kỹ thuật của một file OpenAPI tại đây.
• Swagger UI – hiển thị thông số kỹ thuật OpenAPI dưới dạng tài liệu API tương tác. Cho phép bất cứ ai nhóm phát triển hoặc đối tác người tiêu dùng – tương tác trực tiếp với các tài nguyên API của bạn mà không cần bất cứ logic triển khai nào.
• Swagger Codegen – tạo server cơ bản và thư viện client từ một OpenAPI Specification. Công cụ cung cấp hơn 40 ngôn ngữ để bạn lựa chọn.
• Swagger Hub – có đầy đủ cả 3 công cụ phía trên và cung cấp một domain cho phép chúng ta public Swagger UI. Tất nhiên dịch vụ này có tính phí nhưng bạn vẫn có thể sử dụng bản free trial.
  
  

Sử dụng Swagger?

Để sử dụng Swagger bạn có thể tải về và chạy ở local. Tuy nhiên đây MEVN sẽ hướng dẫn bạn sử dụng online trên website Swagger Hub.Sau khi đăng ký tài khoản trên Swagger Hub. Swagger Hub sẽ đưa bạn đến trang tạo api. Có nhiều mẫu template tùy vào nhu cầu mà bạn có thể lựa chọn theo ý muốn.

Khi tạo thành công api bạn sẽ được đưa đến một trang editor với định dạng file .yaml.

Giao diện trang được chia thành 3 phần. 

Navigation: cột bên trái 

Thanh menu được tạo từ nội dung của file .yaml. Tại đây nội dung file được phân theo từng mục. Bạn có thể dùng nó để điều hướng đến phần nội dung cần xem.

Editor: cột ở giữa

Khung editor sẽ hiển thị nội dung file .yaml và MEVN sẽ giới thiệu đôi chút về các key trong file này.

Info

Mỗi OpenAPI specifications sẽ bắt đầu với từ khóa openapi để khai báo phiên bản (VD: openapi: 3.0.0). Phiên bản này sẽ định nghĩa toàn bộ cấu trúc của API Phân info sẽ chứa những thông tin của API như: title, description (tùy chọn), version.

• title: tên API.
• description : thông tin mô tả về API, có thể viết thành nhiều dòng & hỗ trợ cú pháp Markdown.
• info : thông tin liên hệ, chứng chỉ, điều khoản sử dụng và những thông tin khác.
• version: phiên bản API.
  
  

Servers

Đây là phần sẽ chỉ định đường dẫn của server để. Bạn có thể định nghĩa một hoặc nhiều server. Và MEVN sẽ để cách dùng các đường dẫn này để test APIs ở cuối bài viết.

Tags

Định nghĩa tags, có thể sử dụng để gom những API trong cùng một controllers về một nhóm.

Paths

Đây là phần trọng tâm của API. Ở phần này bạn sẽ định nghĩa những paths trong API của bạn cũng như phương thức, tham số trong API.

• paths trong API (/user/{userId}).
  
  
• Phương thức của API (GET, POST, DELETE, PUT …).
  
  
• summary là phần mô tả tóm tắt của API.
  
  
• parameters: sẽ là những tham số truyền vào API. Bạn có thể set tham số required hay không, mô tả nó (description) hoặc validate. Đặc biệt trong phần này bạn có thể chỉ định 1 schema (Model) để có thể định nghĩa cho phần tham số thông qua schema & $ref.
  
  
• response là phần trả về của server. Dùng để định nghĩa những HTTP code: 200, 404, 500 … với những mô tả cho từng trường hợp.
  
  

Các parameters có khá nhiều khai báo sau từ khóa in mà bạn sẽ phải chú ý đến:

• in: body : tạo một input-text area mà ở đó bạn có thể nhập data body request vào (sử dụng cho methods PATH/ PUT).
  
  
• in: formData : tạo những input đã định trước mà bạn sẽ nhập data request theo từng field đã định sẵn vào (sử dụng cho methods PATH/ PUT).
  
  
• in: path : tạo một input nhập vào giá trị khai báo trong routes, thường là id.
  
  
• in: query : tạo một input nhập vào giá trị theo các field định sẵn để gửi những query request (sử dụng trong methods GET).
  
  
• in: header : khai báo những giá trị trong header của request mà bạn cần truyền lên.
  
  

SecurityDefinitions

Authentication mà APIs sử dụng để cung cấp tài nguyên.

Definitions

Định nghĩa các model sử dụng bởi APIs, bao gồm:

• Tham số đầu tiên là tên của Model (Order).
• Tiếp đó sẽ là phần kiểu (type) định dạng (object).
• Sau đó là phần thuộc tính (properties) của Model này.

UI Docs: cột bên phải

Tại đây ta có thể biết rõ được các thông tin chi tiết về API như: thông tin dự án, các API được cung cấp, method và url tương ứng:

Với mỗi API bạn có thể biết được chi tiết input và output cũng như trường nào bắt buộc gửi lên, kết quả trả về có thể nhận những status nào. Đặc biệt, ta có thể input data để thử kiểm tra kết quả.

Hoặc có cách khác để xem Swagger UI, bạn chọn Design View => Preview Docs.

Để Export ra code gọi APIs, chúng ta chọn Export, chọn dạng mà chúng ta muốn xuất ra.

Ngoài cách dùng Swagger UI thì bạn có thể dùng ứng dụng Postman để kiểm tra và thử nghiệm APIs.

Sử dụng Postman để kiểm tra Api?

Để sử dụng Postman bạn có thể dùng đường dẫn public API mà Swagger cung cấp.

Khi dùng đường dẫn, MEVN đã kết nối thành công đến APIs và lấy được dữ liệu với petId. Các bạn sẽ thấy các dữ liệu như id, category, name… được trả về.

Kết luận

Nói chung Swagger sẽ giúp bạn tạo một file mô tả chi tiết về Api và bạn có thể thử nghiệm Api chạy tốt hay không. Bởi vì document Api là yếu tố quan trọng để có một trải nghiệm tốt khi sử dụng Api. Nó không chỉ làm hài lòng khách hàng mà còn giúp số lượng người sử dụng Api của bạn tăng lên.

Chỉ cần chậm rãi, bạn sẽ nhanh chóng cảm nhận được hiệu quả mà Swagger mang đến với bản thân và cả đối tác của bạn.

Khi đã hiểu mọi thứ và áp dụng vào dự án, đó là cơ sở để bạn có thể tin rằng, APIs của bạn đang hoạt động hiệu quả.

Tuy nhiên sử dụng Swagger Hub lại có 1 nhược điểm là không tách thành cấu trúc file – thư mục, điều này gây file config rất dài và khó maintain. Bạn hãy thử tưởng tượng có 1 hệ thống 100 cái APIs cần public, kiểu dữ liệu to bự chảng … và sau đó cấu hình lỗi 1 APIs thì sẽ sửa thế nào nhỉ 😝.

Trên đây, chúng ta đã tìm hiểu về 1 công cụ viết và quản lý document APIs khá dễ làm quen và tự viết được. Hy vọng bài viết này sẽ giúp ích cho dự án của bạn. Cảm ơn vì đã đọc bài viết của MEVN!