oneOf, allOf, anyOf

oneOf, anyOf và allOf là các từ khóa trong đặc tả JSON Schema, được sử dụng để định nghĩa các cấu trúc dữ liệu tổng hợp. Về bản chất, chúng là các toán tử logic được áp dụng cho việc xác thực dữ liệu. Apidog hỗ trợ đầy đủ các tính năng JSON Schema này, giúp bạn xây dựng tài liệu API và quy tắc xác thực dữ liệu chính xác hơn.

Khái niệm cơ bản

allOf

allOf có nghĩa là dữ liệu phải đồng thời đáp ứng tất cả các điều kiện của schema con, tương đương với phép toán AND trong các phép toán logic. Tương tự cách diễn đạt "vừa... vừa..." trong ngôn ngữ hằng ngày, tất cả điều kiện phải được đáp ứng đồng thời thì quá trình xác thực mới thành công.

anyOf

oneOf

Bảng so sánh logic

Từ khóa	Phép toán logic	Yêu cầu điều kiện	Trường hợp sử dụng điển hình
`allOf`	AND	Phải đáp ứng đồng thời tất cả điều kiện	Kế thừa, mở rộng
`anyOf`	OR	Phải đáp ứng ít nhất một điều kiện	Tổ hợp tùy chọn
`oneOf`	XOR	Phải đáp ứng chính xác một điều kiện	Lựa chọn loại trừ lẫn nhau

Cách sử dụng trong Apidog

1. Sử dụng trình chỉnh sửa trực quan

Bước 1: Tạo schema dữ liệu

Trong dự án của bạn, nhấp vào "Schemas", sau đó nhấp "New Schema".

Bước 2: Thêm thành phần schema

Trong bảng chỉnh sửa schema dữ liệu, khi chọn loại, hãy nhấp vào "Schema Composition" và chọn oneOf, anyOf hoặc allOf. Định nghĩa các cấu trúc dữ liệu cụ thể cho từng schema con.

2. Sử dụng trình chỉnh sửa mã JSON Schema

Bạn cũng có thể trực tiếp chỉnh sửa mã JSON Schema trong bảng chỉnh sửa schema dữ liệu để định nghĩa các mẫu tổng hợp logic này.

Ứng dụng trong tài liệu API

Định nghĩa tham số yêu cầu

Khi định nghĩa tham số yêu cầu của endpoint, bạn có thể sử dụng các mẫu tổng hợp này để mô tả các cấu trúc tham số phức tạp:

Truy cập trang chỉnh sửa API.

Trong phần "Request Parameters", chọn Body và chọn loại JSON.

Trong cấu trúc dữ liệu, nhấp vào "Reference Schema", hoặc chọn "Schema Composition" phù hợp dựa trên logic nghiệp vụ, hoặc định nghĩa JSON Schema tùy chỉnh.

Định nghĩa dữ liệu phản hồi

Tương tự, bạn có thể sử dụng các thành phần schema này trong dữ liệu phản hồi:

Trong phần "Response", thêm các ví dụ phản hồi.

Sử dụng thành phần schema để mô tả các định dạng phản hồi khác nhau.

Ví dụ sử dụng thực tế

Ví dụ allOf (Phép toán AND)

Sử dụng allOf cho phép bạn kết hợp nhiều schema dữ liệu lại với nhau, yêu cầu dữ liệu phải đồng thời đáp ứng tất cả điều kiện. Điều này giống như nói "thông tin người dùng phải bao gồm thông tin cơ bản AND thông tin liên hệ":

{
  "allOf": [
    {
      "description": "Basic user information",
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    },
    {
      "description": "Contact information", 
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      },
      "required": ["email"]
    }
  ]
}

Kết quả: Dữ liệu cuối cùng phải chứa các trường id, name và email, trong đó phone là tùy chọn. Tất cả ràng buộc từ các schema con được hợp nhất và thực thi, như minh họa bên dưới:

Ví dụ anyOf (Phép toán OR)

Sử dụng anyOf cung cấp nhiều đường dẫn xác thực tùy chọn - người dùng có thể chọn một hoặc nhiều phương thức bất kỳ. Điều này giống như nói "người dùng có thể đăng nhập bằng tên người dùng/mật khẩu OR email/mật khẩu OR điện thoại/mã xác minh":

{
  "type": "object",
  "properties": {
    "login": {
      "anyOf": [
        {
          "description": "Username/password login",
          "properties": {
            "username": { "type": "string" },
            "password": { "type": "string" }
          },
          "required": ["username", "password"]
        },
        {
          "description": "Email/password login",
          "properties": {
            "email": { "type": "string", "format": "email" },
            "password": { "type": "string" }
          },
          "required": ["email", "password"]
        },
        {
          "description": "Phone/verification code login",
          "properties": {
            "phone": { "type": "string" },
            "verifyCode": { "type": "string" }
          },
          "required": ["phone", "verifyCode"]
        }
      ]
    }
  }
}

Kết quả: Người dùng có thể cung cấp thông tin cho một hoặc nhiều phương thức đăng nhập bất kỳ, miễn là ít nhất một phương thức đáp ứng các yêu cầu xác thực, như minh họa bên dưới:

Ví dụ oneOf (Phép toán XOR)

Sử dụng oneOf đảm bảo rằng người dùng chỉ có thể chọn một phương thức thanh toán và không thể đồng thời cung cấp nhiều phương thức. Điều này giống như nói "phương thức thanh toán phải là thẻ tín dụng XOR PayPal XOR chuyển khoản ngân hàng - chính xác một trong các tùy chọn này":

{
  "type": "object", 
  "properties": {
    "payment": {
      "oneOf": [
        {
          "description": "Credit card payment",
          "type": "object",
          "properties": {
            "type": { "const": "credit_card" },
            "cardNumber": { "type": "string" },
            "expiryDate": { "type": "string" }
          },
          "required": ["type", "cardNumber", "expiryDate"],
          "additionalProperties": false
        },
        {
          "description": "PayPal payment", 
          "type": "object",
          "properties": {
            "type": { "const": "paypal" },
            "email": { "type": "string", "format": "email" }
          },
          "required": ["type", "email"],
          "additionalProperties": false
        },
        {
          "description": "Bank transfer",
          "type": "object", 
          "properties": {
            "type": { "const": "bank_transfer" },
            "accountNumber": { "type": "string" },
            "routingNumber": { "type": "string" }
          },
          "required": ["type", "accountNumber", "routingNumber"],
          "additionalProperties": false
        }
      ]
    }
  }
}

Kết quả: Người dùng phải chọn chính xác một phương thức thanh toán - họ không thể đồng thời cung cấp nhiều phương thức, cũng không thể không cung cấp phương thức nào, như minh họa bên dưới:

Thực hành tốt nhất

Khi chọn mẫu tổng hợp, trước tiên hãy làm rõ logic nghiệp vụ của bạn:

Cần kết hợp/kế thừa nhiều schema → Sử dụng allOf (phép toán AND)

Cần các tổ hợp tùy chọn linh hoạt → Sử dụng anyOf (phép toán OR)

Cần các lựa chọn loại trừ lẫn nhau nghiêm ngặt → Sử dụng oneOf (phép toán XOR)

Khái niệm cơ bản#

Bảng so sánh logic#

Cách sử dụng trong Apidog#

1. Sử dụng trình chỉnh sửa trực quan#

2. Sử dụng trình chỉnh sửa mã JSON Schema#

Ứng dụng trong tài liệu API#

Định nghĩa tham số yêu cầu#

Định nghĩa dữ liệu phản hồi#

Ví dụ sử dụng thực tế#

Ví dụ allOf (Phép toán AND)#

Ví dụ anyOf (Phép toán OR)#

Ví dụ oneOf (Phép toán XOR)#

Thực hành tốt nhất#