Softonic

Trình kiểm tra OpenAPI

Bước 1 / 2
Tiếp theo

Dán một tài liệu OpenAPI hoặc Swagger, dạng JSON hoặc YAML, và trình kiểm tra này sẽ kiểm tra cấu trúc cốt lõi của nó. Nó xác nhận tài liệu parse được, có trường phiên bản openapi hoặc swagger, có đối tượng info chứa tiêu đề và phiên bản, và có đối tượng paths, rồi đánh dấu những path không bắt đầu bằng dấu gạch chéo và các phương thức HTTP không xác định. Đây là một lần kiểm tra cấu trúc nhanh, không phải trình kiểm tra JSON Schema đầy đủ.

Quá trình kiểm tra diễn ra như thế nào

  1. 1

    Dán tài liệu

    JSON hoặc YAML, cho OpenAPI 2 (Swagger) hoặc OpenAPI 3.

  2. 2

    Parse tài liệu

    Trình kiểm tra parse tài liệu dưới dạng JSON, và chuyển sang parse YAML nếu việc đó thất bại.

  3. 3

    Kiểm tra các trường bắt buộc

    Nó xác nhận trường phiên bản `openapi` hoặc `swagger`, đối tượng `info` chứa `title` và `version`, và đối tượng `paths`.

  4. 4

    Quét các path

    Mỗi path được kiểm tra xem có dấu gạch chéo ở đầu không, và mỗi khóa operation được đối chiếu với các phương thức HTTP đã biết.

  5. 5

    Đọc báo cáo

    Lỗi làm cho tài liệu không hợp lệ; cảnh báo chỉ ra những path không có dấu gạch chéo ở đầu và các phương thức không xác định.

Trình kiểm tra này kiểm tra những gì

Kiểm tra Kết quả nếu thất bại
Tài liệu parse được dạng JSON hoặc YAML Lỗi
Có trường openapi hoặc swagger Lỗi
Có đối tượng info Lỗi
Có info.title Lỗi
Có info.version Lỗi
Có đối tượng paths Lỗi
Mỗi path bắt đầu bằng / Cảnh báo
Khóa operation là phương thức HTTP đã biết Cảnh báo

Tài liệu vượt qua mọi lỗi được báo cáo là hợp lệ về mặt cấu trúc. Cảnh báo không làm tài liệu không hợp lệ; chúng chỉ ra những điểm đáng sửa.

Những gì nó không kiểm tra

Đây là kiểm tra cấu trúc, không phải trình kiểm tra đặc tả đầy đủ. Nó không:

  • xác thực từng nút theo JSON Schema chính thức của phiên bản bạn dùng;
  • giải quyết các tham chiếu $ref hay xác nhận các thành phần mà chúng trỏ tới có tồn tại;
  • kiểm tra xem tham số path có được khai báo và dùng nhất quán không;
  • xác minh giá trị operationId có tồn tại hoặc duy nhất không;
  • báo cáo số dòng của lỗi.

Để đạt độ sâu đó, hãy chạy một trình kiểm tra CLI chuyên dụng như redocly lint, swagger-cli validate hoặc spectral lint. Dùng công cụ này để kiểm tra nhanh trước khi bạn commit hoặc chia sẻ một đặc tả.

Các phiên bản OpenAPI trong thực tế

Phiên bản Ghi chú
Swagger 2.0 Vẫn được triển khai rộng rãi; dùng swagger: "2.0"
OpenAPI 3.0.x Dòng 3.x phổ biến nhất
OpenAPI 3.1.0 Tương thích với JSON Schema 2020-12

Trình kiểm tra này chấp nhận trường openapi (3.x) hoặc trường swagger (2.0), nên tất cả đều vượt qua bước kiểm tra phiên bản.

Một tài liệu tối thiểu vượt qua

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Mọi trường bắt buộc đều có mặt, path duy nhất bắt đầu bằng dấu gạch chéo, và get là một phương thức đã biết, nên tài liệu này được báo cáo là hợp lệ về mặt cấu trúc.

Câu hỏi thường gặp

Swagger là tên ban đầu của đặc tả này, được quyên tặng cho Linux Foundation vào năm 2015 và đổi tên thành “OpenAPI” kể từ phiên bản 3.0. Ngày nay “Swagger” chỉ các công cụ (Swagger UI, Swagger Editor). Bản thân đặc tả là OpenAPI. Trình kiểm tra này chấp nhận cả trường phiên bản swagger (2.0) lẫn openapi (3.x).

Không. Nó kiểm tra cấu trúc cốt lõi: tài liệu parse được, có trường phiên bản, đối tượng info chứa tiêu đề và phiên bản, và đối tượng paths, đồng thời cảnh báo những path không có dấu gạch chéo ở đầu và các phương thức không xác định. Nó không xác thực từng nút theo JSON Schema chính thức. Hãy dùng redocly lint hoặc spectral lint cho việc đó.

Không. Nó không đi theo các tham chiếu $ref hay kiểm tra sự tồn tại của các thành phần mà chúng trỏ tới. Với tham chiếu liên tệp, hãy gộp tài liệu trước bằng một công cụ như redocly bundle hoặc swagger-cli bundle, rồi chạy một trình kiểm tra đầy đủ.

Không. Nó chỉ kiểm tra tài liệu bạn dán, không kiểm tra mã đang chạy. Nó không thể biết API của bạn có thực sự trả về đúng những gì đặc tả mô tả hay không. Các công cụ kiểm thử hợp đồng như Dredd hoặc Schemathesis mới làm việc đó.

Công cụ liên quan

Bảng tham chiếu ASCII

Bảng ASCII đầy đủ từ 0 đến 127 với giá trị thập phân, thập lục phân, bát phân, nhị phân và ký hiệu tham chiếu ký tự số HTML, gồm NUL, LF và DEL.

Tham chiếu ký tự HTML

Danh sách có thể tìm kiếm các thực thể HTML, mã tên và mã số tương ứng của chúng, cùng chức năng sao chép chỉ với một cú nhấp cho các ký tự đặc biệt và biểu tượng.

Bảng tham khảo phím tắt

Tìm phím tắt mặc định theo tài liệu của VS Code, Chrome và Bash dùng GNU Readline trên macOS, Windows và Linux.

Trình định dạng HTML

Định dạng HTML cục bộ trong trình duyệt với thụt lề hai hoặc bốn khoảng trắng. HTML không được tải lên hoặc xác thực.

Bảng tra cứu nhanh Markdown

Tài liệu Markdown thực dụng với bản xem trước thực tế và ví dụ có thể sao chép cho tiêu đề, danh sách, bảng, mã, liên kết, hình ảnh và cú pháp GFM.

Công cụ xác thực số điện thoại

Kiểm tra cấu trúc số theo quốc gia và xem khu vực, loại số cùng các định dạng E.164, quốc tế, quốc gia và RFC 3966.

Công cụ này có phiên bản bằng các ngôn ngữ khác