oneOf, allOf, anyOf

oneOf、anyOf 和 allOf 是 JSON Schema 规范中的关键字，用于定义组合数据结构。它们本质上是应用于数据验证的逻辑运算符。Apidog 完全支持这些 JSON Schema 特性，帮助你构建更准确的 API 文档和数据验证规则。

基本概念

allOf

allOf 表示数据必须同时满足所有子 Schema 条件，等同于逻辑运算中的 AND 操作。就像日常语言中的“既……又……”，所有条件都必须同时满足，验证才能通过。

anyOf

oneOf

逻辑对比表

关键字	逻辑操作	条件要求	典型使用场景
`allOf`	AND	必须同时满足所有条件	继承、扩展
`anyOf`	OR	必须至少满足一个条件	可选组合
`oneOf`	XOR	必须恰好满足一个条件	互斥选择

在 Apidog 中的用法

1. 使用可视化编辑器

步骤 1：创建数据 Schema

在你的项目中，点击 "Schemas"，然后点击 "New Schema"。

步骤 2：添加 Schema 组合

在数据 Schema 编辑面板中，选择类型时，点击 "Schema Composition"，并选择 oneOf、anyOf 或 allOf。为每个子 Schema 定义具体的数据结构。

2. 使用 JSON Schema 代码编辑器

你也可以直接在数据 Schema 编辑面板中编辑 JSON Schema 代码，以定义这些逻辑组合模式。

在 API 文档中的应用

请求参数定义

定义端点请求参数时，你可以使用这些组合模式来描述复杂的参数结构：

进入 API 编辑页面。

在 "Request Parameters" 部分，选择 Body 并选择 JSON 类型。

在数据结构中，点击 "Reference Schema"，或根据业务逻辑选择合适的 "Schema Composition"，也可以定义自定义 JSON Schema。

响应数据定义

同样，你可以在响应数据中使用这些 Schema 组合：

在 "Response" 部分，添加响应示例。

使用 Schema 组合来描述不同的响应格式。

实际使用示例

allOf 示例（AND 操作）

使用 allOf 可以将多个数据 Schema 组合在一起，要求数据同时满足所有条件。这就像是在说“用户信息必须包含基本信息 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 为可选字段。来自子 Schema 的所有约束都会被合并并执行，如下所示：

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

结果： 用户必须恰好选择一种支付方式——不能同时提供多种方式，也不能一种都不提供，如下所示：

最佳实践

选择组合模式时，首先明确你的业务逻辑：

需要组合/继承多个 Schema → 使用 allOf（AND 操作）

需要灵活的可选组合 → 使用 anyOf（OR 操作）

需要严格的互斥选择 → 使用 oneOf（XOR 操作）

基本概念#

逻辑对比表#

在 Apidog 中的用法#

1. 使用可视化编辑器#

2. 使用 JSON Schema 代码编辑器#

在 API 文档中的应用#

请求参数定义#

响应数据定义#

实际使用示例#

allOf 示例（AND 操作）#

anyOf 示例（OR 操作）#

oneOf 示例（XOR 操作）#

最佳实践#