Cách dùng Kiểm tra OpenAPI / Swagger
- Dán
openapi.yaml/swagger.jsonvào hoặc mở file. - Phiên bản (OpenAPI 3.1, 3.0 hoặc Swagger 2.0) sẽ được tự động nhận diện.
- Sửa các lỗi schema trước — mỗi lỗi đều hiển thị vị trí của nó trong tài liệu.
- Xem lại các kiểm tra bổ sung và danh sách endpoint.
Những gì được kiểm tra
| Kiểm tra | Chi tiết |
|---|---|
| Schema chính thức | Tài liệu được kiểm tra theo JSON Schema của OpenAPI Initiative cho phiên bản tương ứng (3.1, 3.0 hoặc Swagger 2.0): các trường bắt buộc, khóa được phép, kiểu giá trị |
$ref bị hỏng | Mọi tham chiếu nội bộ (#/components/schemas/Pet) phải trỏ tới một thành phần có thật |
operationId duy nhất | Trùng lặp sẽ làm hỏng bộ sinh SDK và các liên kết tài liệu |
| Tham số path | Mỗi {param} trong path phải được khai báo với in: path và required: true, và ngược lại |
| Responses | Mỗi operation cần ít nhất một response |
| Gợi ý | Thiếu operationId, servers hoặc info.description |
Các phiên bản OpenAPI
- Swagger 2.0 —
swagger: "2.0",definitions,host/basePath. - OpenAPI 3.0 —
components,servers,requestBody; schema là tập con của JSON Schema draft-04 và có thêmnullable. - OpenAPI 3.1 — đồng bộ hoàn toàn với JSON Schema 2020-12 (
type: [string, "null"]thay chonullable), bổ sungwebhooks.
Giới hạn
Các tham chiếu bên ngoài tới file khác hoặc URL sẽ không được tải về — hãy gộp spec nhiều file trước (ví dụ bằng redocly bundle). Kiểm tra schema chỉ báo lỗi cấu trúc; các quy tắc về phong cách như quy ước đặt tên cần một linter như Spectral. Bạn có thể kiểm tra payload mẫu theo schema bằng JSON Schema validator, kiểm tra cú pháp YAML bằng YAML validator, và thử API trực tiếp với API tester.
Cũng được tìm dưới tên: kiểm tra openapi, swagger validator, validate openapi, openapi 3.1 validator, kiểm tra swagger 2.0, openapi lint, kiểm tra file swagger online.
Các công cụ dùng kèm tốt với Kiểm tra OpenAPI / Swagger
- Định dạng JSON — Dán JSON để định dạng đẹp, nén hoặc kiểm tra.
- Chuyển cURL sang Code — Dán lệnh curl từ tài liệu API hoặc “Copy as cURL” trong DevTools của trình duyệt, rồi nhận ngay đoạn code chạy được cho sáu ngôn ngữ, giữ nguyên header, body và thông tin xác thực.
- Kiểm Thử JSONPath — Nhập truy vấn JSONPath và xem ngay nó chọn ra những gì, kèm đường dẫn chính xác của từng kết quả.
- JSON sang YAML — Dán JSON để nhận YAML sạch cho manifest Kubernetes, Docker Compose, GitHub Actions hoặc bất kỳ file cấu hình nào.
Câu hỏi thường gặp
Công cụ có hỗ trợ OpenAPI 3.1 không?
Có — OpenAPI 3.1.x, 3.0.x và Swagger 2.0 đều được kiểm tra theo schema chính thức tương ứng.
Tại sao một lỗi nhỏ lại báo nhiều lỗi?
Schema chính thức dùng các lựa chọn thay thế (oneOf), nên một giá trị sai có thể làm hỏng nhiều nhánh cùng lúc. Công cụ đã lọc lại các thông báo cụ thể nhất; hãy sửa lỗi đầu tiên rồi kiểm tra lại.
Công cụ có theo được $ref tới file khác không?
Không, chỉ hỗ trợ tham chiếu trong cùng một tài liệu. Hãy gộp spec nhiều file thành một file trước.
Spec API của tôi có bị tải lên không?
Không. Việc kiểm tra chạy hoàn toàn trên trình duyệt của bạn, nên thiết kế API nội bộ luôn được giữ riêng tư.
Tôi có thể cài Kiểm tra OpenAPI / Swagger như một ứng dụng web và dùng khi không có mạng không?
Có. Kiểm tra OpenAPI / Swagger là một ứng dụng web (PWA) có thể cài đặt — cài trực tiếp từ trình duyệt, không cần tải từ cửa hàng ứng dụng. Trên Chrome hoặc Edge (Windows, macOS, Linux, ChromeOS) hoặc Android, bấm Cài đặt ứng dụng ở đầu trang này; trên iPhone và iPad, dùng Chia sẻ → Thêm vào Màn hình chính; trên Mac, dùng File → Add to Dock trong Safari 17 trở lên. Sau đó ứng dụng mở trong cửa sổ riêng với biểu tượng riêng, và vì chạy hoàn toàn trên trình duyệt nên vẫn hoạt động khi không có mạng. Firefox trên máy tính không thể cài ứng dụng web. Cách cài đặt hoạt động thế nào.