oneOf, allOf, anyOf

oneOf、anyOf 和 allOf 是 JSON Schema 規格中的關鍵字，用於定義複合資料結構。它們本質上是套用於資料驗證的邏輯運算子。Apidog 完全支援這些 JSON Schema 功能，協助你建立更精確的 API 文件與資料驗證規則。

基本概念

allOf

allOf 表示資料必須同時滿足所有子結構描述條件，等同於邏輯運算中的 AND 運算。就像日常語言中的「既……又……」，所有條件都必須同時滿足，驗證才會通過。

anyOf

oneOf

邏輯比較表

關鍵字	邏輯運算	條件要求	典型使用情境
`allOf`	AND	必須同時滿足所有條件	繼承、擴充
`anyOf`	OR	必須至少滿足一個條件	可選組合
`oneOf`	XOR	必須剛好滿足一個條件	互斥選項

在 Apidog 中的使用方式

1. 使用視覺化編輯器

步驟 1：建立資料結構描述

在你的專案中，點選 "Schemas"，然後點選 "New Schema"。

步驟 2：新增結構描述組合

在資料結構描述編輯面板中，選擇類型時，點選 "Schema Composition"，並選擇 oneOf、anyOf 或 allOf。為每個子結構描述定義特定的資料結構。

2. 使用 JSON Schema 程式碼編輯器

你也可以直接在資料結構描述編輯面板中編輯 JSON Schema 程式碼，以定義這些邏輯組合模式。

在 API 文件中的應用

請求參數定義

定義端點請求參數時，你可以使用這些組合模式來描述複雜的參數結構：

進入 API 編輯頁面。

在 "Request Parameters" 區段中，選擇 Body 並選擇 JSON 類型。

在資料結構中，點選 "Reference Schema"，或根據業務邏輯選擇適當的 "Schema Composition"，或定義自訂 JSON Schema。

回應資料定義

同樣地，你也可以在回應資料中使用這些結構描述組合：

在 "Response" 區段中，新增回應範例。

使用結構描述組合來描述不同的回應格式。

實際使用範例

allOf 範例（AND 運算）

使用 allOf 可讓你將多個資料結構描述組合在一起，要求資料同時滿足所有條件。這就像是說「使用者資訊必須包含基本資訊 AND 聯絡資訊」：

{
  "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"]
    }
  ]
}

結果： 最終資料必須包含 id、name 和 email 欄位，phone 則為選填。所有來自子結構描述的限制都會合併並執行，如下所示：

anyOf 範例（OR 運算）

使用 anyOf 可提供多個可選的驗證路徑——使用者可以選擇任一種或多種方法。這就像是說「使用者可以透過使用者名稱/密碼登入 OR 電子郵件/密碼 OR 電話/驗證碼」：

{
  "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"]
        }
      ]
    }
  }
}

結果： 使用者可以提供任一種或多種登入方式的資訊，只要至少一種方式滿足驗證要求即可，如下所示：

oneOf 範例（XOR 運算）

使用 oneOf 可確保使用者只能選擇一種付款方式，且不能同時提供多種方式。這就像是說「付款方式必須是信用卡 XOR PayPal XOR 銀行轉帳——這些選項中剛好選一個」：

{
  "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
        }
      ]
    }
  }
}

結果： 使用者必須剛好選擇一種付款方式——不能同時提供多種方式，也不能完全不提供，如下所示：

最佳實務

選擇組合模式時，請先釐清你的業務邏輯：

需要組合/繼承多個結構描述 → 使用 allOf（AND 運算）

需要彈性的可選組合 → 使用 anyOf（OR 運算）

需要嚴格的互斥選項 → 使用 oneOf（XOR 運算）

基本概念#

邏輯比較表#

在 Apidog 中的使用方式#

1. 使用視覺化編輯器#

2. 使用 JSON Schema 程式碼編輯器#

在 API 文件中的應用#

請求參數定義#

回應資料定義#

實際使用範例#

allOf 範例（AND 運算）#

anyOf 範例（OR 運算）#

oneOf 範例（XOR 運算）#

最佳實務#