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 (http://commonmark.org/help/) or HTML. version: 0.1.9
3.2: Servers
Đang xem: Userid là gì, bạn hiểu gì về công cụ viết document cho api
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
Xem thêm: Tra Từ Worm Gear Là Gì – Từ Điển Anh Việt Worm Gear Or Worm Wheel Là Gì
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”
Xem thêm: Chè Khúc Bạch Là Gì – Vì Sao Ai Cũng “Ghiền” Món Chè Kết Hợp Âu
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