Công cụ kiểm tra Swagger 2.0

Điều gì được tính là đạt đối với Swagger 2.0

Với tệp 2.0, kiểm tra phiên bản được thỏa mãn bởi một khóa swagger ở cấp cao nhất. Công cụ không xác minh giá trị của nó có phải là "2.0" hay không, nên nó sẽ không bắt được một số sai. Ngoài phiên bản, cần có info.title, info.version và một đối tượng paths.

Các trường riêng của Swagger 2.0, như host, basePath, schemes, definitions và securityDefinitions, không được kiểm tra. Thiếu host hoặc khối definitions bị hỏng sẽ không được báo.

Ví dụ minh họa

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

Trường phiên bản, info và paths đều có mặt nên không có lỗi. Báo cáo hiển thị một cảnh báo:

Tài liệu vẫn được báo là hợp lệ vì cảnh báo không chặn tính hợp lệ. Các khóa mở rộng của nhà cung cấp như x-internal là hợp lệ trong Swagger 2.0, nên bạn có thể giữ nguyên.

Di chuyển từ 2.0

Nếu bạn định chuyển sang OpenAPI 3.x, bạn có thể dán tệp đã chuyển đổi vào cùng ô nhập và so sánh kết quả. Kiểm tra giống nhau, chỉ khác là trường openapi thay thế swagger. Với công việc di chuyển thực sự, hãy dùng bộ chuyển đổi và linter đầy đủ, vì công cụ này không dịch các thiết lập definitions hoặc host.

Khi kiểm tra nhanh là đủ

Các định nghĩa Swagger 2.0 thường tồn tại nhiều năm trong kho mã và được sửa tay. Kiểm tra cấu trúc nhanh hữu ích khi bạn tiếp nhận một định nghĩa như vậy, khi một công cụ từ chối tải nó và bạn nghi có trường bị thiếu, hoặc khi bạn gộp hai tệp và muốn chắc kết quả vẫn có các phần info và paths. Để biết đầy đủ quy tắc 2.0, bao gồm definitions và thiết lập bảo mật, hãy dùng một linter chuyên dụng.

Hãy nhớ rằng báo cáo sạch chỉ là một khẳng định về cấu trúc. Thao tác không có phản hồi, sai kiểu tham số và tham chiếu chưa được phân giải nằm ngoài kiểm tra này, nên hãy thử tệp trong công cụ tài liệu hoặc sinh mã của bạn.