1. OpenAPI là gì

OpenAPI Specification là một định dạng mô tả API dành cho REST APIs. Một file OpenAPI cho phép bạn mô tả toàn bộ API bao gồm cả

• Cho phép những endpoints (/users) và cách thức hoạt động của mỗi endpoint (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ì

Swagger là một bộ công cụ mã nguồn mở để xây dựng OpenAPI specifications giúp bạn có thể thiết kế, xây dựng tài liệu và sử dụng REST APIs

3. Cấu trúc cơ bản

3.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ư: title, desscription (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

3.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 server Tấ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.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 (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 (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

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

Trên đây mình đã hướng dẫn sơ qua về những tính năng của swagger mà mình đã sử dụng trong dự án Các bạn có thể vào link để có thể viết API 1 cách tiện nhất. Nó sẽ render UI ngay lập tức cho bạn