- Trong thời đại công nghệ số hiện nay, các ứng dụng thường xuyên giao tiếp với nhau thông qua các giao diện lập trình ứng dụng (API). Tuy nhiên, ngay cả những API tốt nhất cũng chỉ thực sự phát huy hiệu quả khi có tài liệu hướng dẫn rõ ràng và dễ hiểu. Đây là lý do APIDocs ra đời nhằm tạo điều kiện thuận lợi cho các nhà phát triển trong việc tiếp cận và sử dụng tài liệu.
APIDocs Là Gì?
- Tài liệu API (APIDocs) giống như một hướng dẫn sử dụng cho API của bạn. Tài liệu này không chỉ cung cấp hướng dẫn về cách sử dụng và tích hợp API mà còn đảm bảo rằng các nhà phát triển có đầy đủ thông tin cần thiết để tương tác với API một cách hiệu quả.
Tại Sao Cần APIDocs?
- Hãy tưởng tượng bạn đang cố gắng lắp ráp một món đồ nội thất phức tạp mà không có bất kỳ hướng dẫn nào. Nó sẽ rất khó khăn và khó chịu. Lập trình cũng tương tự; nếu không có tài liệu API thích hợp, các nhà phát triển có thể gặp khó khăn trong việc hiểu cách hoạt động của API, các tham số đầu vào và đầu ra.
Điểm Mạnh và Yếu Của APIDocs
Điểm Mạnh
- Hiểu Biết Rõ Ràng: Tài liệu API được viết tốt giúp cung cấp một nguồn kiến thức duy nhất về cách API hoạt động, giúp các nhà phát triển dễ dàng nắm bắt các điểm cuối.
- Tích Hợp Nhanh Hơn: Tài liệu giúp tiết kiệm thời gian và công sức cho các nhà phát triển trong quá trình tích hợp, vì họ không cần phải tìm hiểu mã hoặc đưa ra các giả định.
- Giảm Lỗi: Tài liệu rõ ràng và chính xác giúp ngăn ngừa lỗi trong quá trình tích hợp thông qua việc cung cấp thông tin đầy đủ về định dạng, tham số và phản hồi yêu cầu.
- Thông Tin Nhất Quán: Tài liệu API đóng vai trò như một ngôn ngữ chung giữa các nhóm phát triển frontend, backend và API, cải thiện sự giao tiếp và hợp tác.
Điểm Yếu
- Cần Cập Nhật Liên Tục: Tài liệu cần được cập nhật ngay khi có bất kỳ sự thay đổi nào đối với API, điều này có thể gây bất tiện cho những người mới bắt đầu sử dụng APIDocs.
- Khó Khăn Trong Tích Hợp: Việc tích hợp APIDocs có thể tốn thời gian khi bạn chưa quen với cách sử dụng.
Công Cụ Tạo Tài Liệu API
- Swagger (OpenAPI): Một bộ công cụ nổi tiếng giúp thiết kế, viết tài liệu và thử nghiệm API.
- Postman: Một nền tảng để xây dựng, thử nghiệm và ghi lại API.
Cài Đặt Swagger Trong Rust
Để cài đặt Swagger, bạn cần thêm các thư viện sau vào tệp Cargo.toml:
swagger = "6.5.0"
utoipa = {version = "4.2.3",features = ["axum_extras"]}
utoipa-swagger-ui = {version = "7.1.0",features = ["axum"]}LƯU Ý: Tôi đang sử dụng Axum cho web service, bạn cũng có thể sử dụng các thư viện khác như actix-web, warp, tide, hoặc rocket.
Tạo Tài Liệu API Với Swagger
- Tạo một tệp có tên
swagger.rsvà sử dụng mã sau:
rust
#[derive(OpenApi)]
#[openapi(
paths(
// Bao gồm các hàm route của bạn tại đây, với các tags tương ứng
crate::routes::users::get_user_id,
crate::routes::products::create_product,
),
components(
schemas(User, Product, ObjectId) // Liệt kê các mô hình dữ liệu của bạn
),
tags(
(name = "users", description = "Các điểm cuối quản lý người dùng"),
(name = "products", description = "Các điểm cuối quản lý sản phẩm")
)
)]
pub struct ApiDoc;- Trong tệp
user_controller.rs, thêm mã sau để định nghĩa các điểm cuối:
rust
#[utoipa::path(
post,
path="/v1/api/create_user",
request_body = CreateUserRequest,
tag = "user",
responses(
(status = 200, description="Tạo người dùng thành công", body= User),
(status = 500, description="Có lỗi trong quá trình cập nhật người dùng", body=APIError),
(status = 404, description="Email đã tồn tại trong cơ sở dữ liệu", body=APIError)
),
)]
pub async fn create_userLƯU Ý: Đảm bảo rằng
pathphải giống với endpoint bạn đã cài đặt trong các route để tránh bị lỗi.
- Trong tệp
route_user.rs, định nghĩa router cho người dùng:
rust
pub fn user_router() -> Router {
Router::new()
.route("/v1/api/create_user", post(create_user))
}- Cuối cùng, trong tệp
main.rs, khởi tạo máy chủ Axum:
rust
#[tokio::main]
async fn main() {
// ... kết nối đến cơ sở dữ liệu và thiết lập khác
// Khởi tạo router API
let app = Router::new()
.merge(create_router(db))
.merge(SwaggerUi::new("/swagger/api-docs").url("/api-docs/openapi.json", ApiDoc::openapi()));
// ... chạy máy chủ Axum
}Xem Tài Liệu API
Truy cập vào tài liệu API tại đường dẫn:
http://localhost:3000/swagger/api-docs.
Bằng cách làm theo các bước trên, bạn có thể dễ dàng tạo tài liệu API với Swagger trong Rust. Hãy nhớ rằng, các kiểu dữ liệu trong Swagger thường là các kiểu nguyên thủy như string, number, boolean, array, và object. Nếu bạn sử dụng các kiểu dữ liệu phức tạp hơn như ObjectID trong MongoDB, hãy lưu ý rằng Swagger sẽ tự động chuyển đổi sang string mà không làm ảnh hưởng đến hoạt động của code.
source: viblo
