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 độngPhương thức xác thựcThô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 APIPhâ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ạndescription 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 Markdowninfo 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
3.2: Servers
Đây là phần sẽ chỉ định đường dẫn của server để ta có thể test được API.
Đang xem: Tìm hiểu về swagger là gì, bạn hiểu gì về công cụ viết document cho api?
Xem thêm: Bệnh Viện Đa Khoa Quốc Tế Vinmec Là Gì, Tập Đoàn Vingroup
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 pathsSau đó 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 APIparameters: 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 & $refresponse 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ự ánCá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