Tìm hiểu về Swagger để viết API
This post hasn't been updated for 3 years
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ạ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ápMarkdown
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 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 quaschema
&$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
All Rights Reserved