Validate theo đặc tả OpenAPI/Swagger

OpenAPI là gì

OpenAPI (trước đây gọi là Swagger) là 1 định dạng chuẩn (thường viết bằng YAML/JSON) để mô tả API: có những endpoint nào, mỗi endpoint nhận tham số gì, response trả về cấu trúc ra sao. Vì đây là định dạng máy đọc được, có thể dùng tool tự động validate response thật khớp với đặc tả.

# Trích đoạn OpenAPI mô tả response của GET /v1/orders/{orderId}
responses:
  '200':
    content:
      application/json:
        schema:
          type: object
          required: [orderId, customerId, status, total]
          properties:
            orderId: { type: string }
            customerId: { type: string }
            status: { type: string, enum: [PENDING, PAID, CANCELLED] }
            total: { type: number, minimum: 0 }

Với schema này, 1 tool validate tự động sẽ báo lỗi ngay nếu response thật thiếu field total, hoặc trả status với giá trị ngoài 3 giá trị enum đã khai báo, hoặc total là số âm.

Checklist kiểm tra

📎 Nội dung do maiqai.com biên soạn — ví dụ minh hoạ, không thuộc hệ thống thật nào.