Công cụ kiểm tra OpenAPI JSON

Các lỗi JSON thường gặp khiến kiểm tra thất bại

JSON nghiêm ngặt hơn YAML, nên hầu hết lỗi trong tệp chỉnh sửa tay đến từ cú pháp chứ không phải thiết kế API. Các nguyên nhân phổ biến là dấu phẩy sau thuộc tính cuối cùng, dấu nháy đơn thay vì nháy kép, chú thích (JSON không cho phép), hoặc thiếu dấu ngoặc nhọn đóng sau một đối tượng paths dài. Tệp bị hỏng thường kết thúc bằng thông báo “Could not parse as JSON or YAML”, hoặc lỗi thiếu trường vì không đọc được gì hữu ích.

Nếu bạn chỉ thấy lỗi phân tích cú pháp, hãy tìm lỗi cú pháp trước. Các kiểm tra cấu trúc chỉ chạy khi tài liệu được đọc như một đối tượng.

Ví dụ minh họa

Hãy lấy tài liệu nhỏ sau:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Tài liệu này phân tích được, và trường openapi cùng đối tượng paths đều có mặt. Báo cáo vẫn hiển thị:

Vì có một lỗi, tài liệu không được báo là hợp lệ. Thêm "version": "1.0.0" vào info và đổi tên khóa thành /orders. Chạy lại sẽ xóa cả hai phát hiện.

Đạt nghĩa là gì và không nghĩa là gì

Báo cáo sạch chỉ có nghĩa là khung sườn đúng. Nó không đi theo liên kết $ref, không kiểm tra schema và không xác nhận mọi thao tác đều có phản hồi. Hãy xem đây là cổng kiểm tra nhanh trước khi bạn commit tệp, sau đó chạy linter đầy đủ để kiểm tra các quy tắc sâu hơn.

Quy trình thực tế cho đặc tả JSON

Lưu đặc tả trong hệ thống quản lý phiên bản và dán vào đây trước mỗi commit chạm vào paths. Vì kiểm tra nhanh, nó đóng vai trò như bước kiểm tra tỉnh táo sau khi gộp thay đổi của nhiều người, khi các khóa trùng lặp hoặc dấu ngoặc đặt sai dễ xảy ra nhất. Nếu JSON của bạn được sinh ra bởi một script build, hãy dán kết quả đã sinh ra thay vì mẫu, để kiểm tra đúng những gì người đọc sẽ nhận được. Khi báo cáo sạch, bạn có thể chia sẻ tệp hoặc đưa cho công cụ sinh tài liệu với sự tự tin hơn rằng cấu trúc cấp cao nhất ổn.