Get in touch
or send us a question?
CONTACT

Tìm hiểu về Swagger

Swagger là gì?

1. OpenAPI là gì?

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.
  • Các tham số đầu vào & đầu ra của từng hoạt động
  • Phương thức xác thực
  • Thông tin liên lạc, chứng chỉ, điều khoản sử dụng và những thông tin khác

API specifications có thể được viết bằng YAML hoặc JSON. Định dạng này dễ đọc, dễ hiểu cho cả người dùng lẫn ngôn ngữ máy tính.

2. 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. 

Cấu trúc cơ bản

1: Metadata

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ư: titledesscription (tùy chọn), version

  • title là tên API của bạn
  • description là thông tin mở rộng về API của bạn. Bạn có thể viết thành nhiều dòng & hỗ trợ cú pháp Markdown
  • info cũng hỗ trợ những từ khóa về thông tin liên lạc, chứng chỉ, điều khoản sử dụng và những thông tin khác
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

2: Servers

Đây là phần sẽ chỉ định đường dẫn của server để ta có thể test được API. Bạn có thể định nghĩa một hoặc nhiều serverTất cả đường dẫn API sẽ là đường dẫn tương đối của URL mà bạn định nghĩa. Ảnh bên phải là phần UI sẽ hiển thị ra

3: 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

  • Phần này sẽ bắt đầu bằng từ khóa paths
  • Sau đó là đến những path trong API (/user/{userId})
  • Tiếp đến là phương thức của API (GETPOSTDELETEPUT …)
  • 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 (hiểu nôm na là 1 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. Bạn có thể định nghĩa những HTTP code: 200, 404, 500 … với những mô tả cho từng trường hợp

4: Schema

Bạn có thể hiểu nôm na đây là 1 Model. Phần này được khai báo qua từ khóa component & schemas (Lưu ý: những chỗ gọi đến schema này phải chỉ định chính xác đường dẫn VD $ref: "#/components/schemas/User" 

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