Dùng JSON Schema để tài liệu hóa API contracts, kiểm tra JSON payloads và tạo mock data thực tế cho test và demo.
Bước 1 – Bắt đầu từ dữ liệu mẫu thực tế
- Trước tiên, dán phản hồi API, request payload hoặc config JSON thật vào formatter để làm sạch.
- Giữ một ví dụ JSON chuẩn cho mỗi endpoint để tránh schema bị lệch theo thời gian.
Bước 2 – Tạo schema nền
- Dùng Schema Generator để suy luận kiểu, trường bắt buộc và cấu trúc lồng nhau.
- Tinh chỉnh mô tả, format và các ràng buộc (min/max, pattern) cho môi trường production.
Bước 3 – Validate JSON theo schema
- Dán schema và payload thật vào Schema Validator để kiểm tra.
- Sửa lỗi bằng cách cập nhật JSON mẫu (bug) hoặc schema (thay đổi hợp đồng).
Bước 4 – Tạo mock data để test
- Mở Mock Generator để tạo payload mẫu thực tế khớp với schema của bạn.
- Dùng seed + batch size để dữ liệu test có thể tái tạo và dễ mở rộng.
Bước 5 – Chia sẻ và tái sử dụng
- Lưu schema vào version control và liên kết trong tài liệu API.
- Tạo typed code (TypeScript/Java/etc.) từ các JSON mẫu ổn định.
Lưu ý quan trọng về tính năng JSON Schema
- Một số schema phụ thuộc vào keyword nâng cao như
$ref, anyOf, oneOf, và allOf. - Mỗi validator hỗ trợ draft và keyword khác nhau; hãy dùng JSON Schema validator đầy đủ trong CI nếu cần tuân thủ nghiêm ngặt.
Ví dụ: JSON → JSON Schema (rút gọn)
// JSON input
{
"id": 1,
"name": "Maeve Winters",
"active": true,
"tags": ["developer", "backend"]
}
// Generated schema (example)
{
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"active": { "type": "boolean" },
"tags": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["id", "name", "active", "tags"]
}