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

Bốn phần bắt buộc

Giá trị info.version là phiên bản của chính API của bạn, không phải phiên bản của đặc tả OpenAPI. Mọi người thường bỏ qua trường này vì phiên bản đặc tả đã có ở đầu tài liệu.

Ví dụ khi mọi thứ đều thiếu

servers:
  - url: https://api.example.com

Tài liệu nhỏ này không có phần bắt buộc nào. Báo cáo liệt kê ba lỗi:

Khi toàn bộ đối tượng info không có, công cụ chỉ báo một lỗi đó và không liệt kê riêng title và version. Hãy thêm info với cả hai trường, và lần chạy tiếp theo sẽ báo nếu một trong hai vẫn còn thiếu.

Khung sườn khởi đầu

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Khung sườn này vượt qua mọi kiểm tra trường bắt buộc. Thay tên bằng tên của bạn và mở rộng từ đó. Phản hồi, schema và bảo mật không thuộc phạm vi kiểm tra này.

Nên chạy kiểm tra này khi nào

Hãy chạy khi bạn bắt đầu một đặc tả mới từ đầu, sau khi sinh đặc tả từ mã nguồn, và trước khi gửi cho bất kỳ ai sẽ nhập nó vào công cụ khác. Nhiều công cụ nhập dừng ở trường bắt buộc đầu tiên bị thiếu với một thông báo ngắn, nên bắt được tất cả trong một lần chạy sẽ tiết kiệm vài vòng qua lại. Đây cũng là lời nhắc hữu ích cho người mới, vốn thường quên info.version hoặc bỏ sót paths khi phác thảo API.

Sau khi các trường bắt buộc đạt, những bổ sung hữu ích tiếp theo là một description ngắn dưới info, một mục servers và một operationId cho mỗi thao tác. Không mục nào trong số này được kiểm tra ở đây, nhưng chúng giúp đặc tả dễ đọc hơn và dễ chuyển thành mã client.