Công cụ kiểm tra OpenAPI YAML

Vì sao thụt đầu dòng ảnh hưởng đến kết quả

Trong YAML, mức lồng nhau của các khóa quyết định trường thuộc đối tượng nào. Nếu version nằm cùng mức thụt với info thay vì thấp hơn một cấp, tài liệu vẫn là YAML đọc được, nhưng info.version bị thiếu và kiểm tra sẽ báo lỗi đó. Điều tương tự cũng áp dụng cho paths: nếu một khóa đường dẫn vô tình bị thụt vào dưới info, đối tượng paths ở cấp cao nhất sẽ biến mất.

Hãy dùng dấu cách, không dùng tab, và giữ một bước thụt nhất quán, chẳng hạn hai dấu cách mỗi cấp.

Ví dụ minh họa

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

Trường version, info.title và paths đều có mặt, và /pets bắt đầu bằng dấu gạch chéo với get là phương thức đã biết. Chỉ thiếu một thứ: info.version. Báo cáo liệt kê:

Thêm version: 1.0.0 dưới info, thụt hai dấu cách, và tài liệu sẽ được báo là hợp lệ về cấu trúc.

Giữ tài liệu đơn giản để đọc đáng tin cậy

Kiểm tra đọc tốt nhất các ánh xạ YAML thông thường: các dòng khóa: giá trị đơn giản được lồng nhau với thụt đầu dòng nhất quán. Nếu một tài liệu dùng các tính năng YAML nâng cao, như anchor hoặc khối nhiều dòng, và bị báo là không đọc được hoặc hiển thị trường bị thiếu, hãy thử một bản JSON của cùng đặc tả để xem vấn đề nằm ở nội dung hay ở cú pháp YAML.

Kết quả sạch chỉ xác nhận khung sườn. Nó không phân giải liên kết $ref và không kiểm tra schema.

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

Chỉnh sửa theo từng bước nhỏ và kiểm tra lại thường xuyên. Sau khi thêm đường dẫn mới hoặc di chuyển một khối, hãy dán lại tệp để bắt được thụt đầu dòng sai khi thay đổi còn mới. Khi bạn tách một đặc tả lớn thành nhiều tệp, hãy dán phiên bản đã gộp, vì kiểm tra này chỉ đọc văn bản bạn đưa vào và không tải các tệp khác. Hãy sao chép từ trình soạn thảo thay vì từ trang web đã hiển thị, vì trang web có thể thay dấu cách và dấu nháy bằng các ký tự trông giống nhưng làm thay đổi cách đọc YAML.

Cuối cùng, hãy nhớ rằng báo cáo chỉ bao gồm những gì kiểm tra có thể thấy. Kết quả sạch trên tệp YAML nghĩa là khung sườn cấp cao nhất đúng, chứ không có nghĩa mọi thao tác, schema hay tham chiếu bên trong đều đúng.