Công cụ kiểm tra OpenAPI 3.1

Công cụ xử lý các tệp 3.1 như thế nào

Phiên bản 3.1 đồng bộ các schema với JSON Schema 2020-12. Bộ xác thực này hoàn toàn không đọc bên trong schema. Nó chỉ kiểm tra cấp cao nhất và các mục đường dẫn, nên các tính năng schema của 3.1 như mảng kiểu hay const ở đây không được xem là đạt hay không đạt. Giá trị phiên bản cũng không được kiểm tra: mọi trường openapi đều được coi là có mặt.

Hai mẫu 3.1 cần lưu ý

OpenAPI 3.1 cho phép tài liệu chỉ mô tả webhooks và bỏ qua paths. Công cụ này bắt buộc có paths, nên một tệp như vậy bị báo lỗi dù đặc tả cho phép. Thêm một đối tượng paths: {} rỗng sẽ đáp ứng kiểm tra.

Danh sách phương thức được dùng ở đây gồm get, post, put, patch, delete, head, options, cộng với parameters, summary, description và servers. Phương thức trace có trong đặc tả nhưng không có trong danh sách này, nên nó tạo ra cảnh báo mà bạn có thể bỏ qua nếu đó là chủ đích. Cảnh báo không làm tài liệu trở nên không hợp lệ.

Ví dụ minh họa

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Kết quả: một lỗi, “Missing ‘paths’ object.” Thêm paths: {} và cấu trúc sẽ đạt.

Khi nào nên dùng công cụ này và khi nào cần làm thêm

Dùng trang này để xác nhận tệp 3.1 có đúng cấu trúc trước khi bạn mở pull request hoặc chia sẻ với đối tác. Các kiểm tra diễn ra nhanh và thông báo rõ ràng. Khi cấu trúc đã đúng, các quy tắc schema 3.1 vẫn cần một linter đầy đủ, vì phần lớn lỗi thực tế nằm ở đó: khai báo kiểu không hợp lệ, tham chiếu bị hỏng và thiếu định nghĩa phản hồi. Hãy coi hai bước này là bổ trợ cho nhau, không phải lựa chọn thay thế.

Nếu một cảnh báo được đánh dấu là chủ đích, chẳng hạn trace, hãy ghi chú trong pull request để người review không phải thắc mắc. Cảnh báo không bao giờ thay đổi kết quả hợp lệ, nên có thể giữ nguyên. Lỗi mới là những mục cần xử lý trước khi chia sẻ tệp.