OpenAPIにおけるoneOf / allOf / anyOfの使い方

oneOf、anyOf、allOfは、JSON Schema仕様で定義されている複合データ構造を表現するためのキーワードです。これらはデータバリデーションに論理演算子として機能し、ApidogではこれらのJSON Schema機能を完全にサポートしています。これにより、より精度の高いAPIドキュメントやデータ検証ルールの構築が可能となります。

基本概念

allOf

allOfは、データがすべてのサブスキーマ条件を同時に満たす必要があることを意味します。論理演算でいうAND（かつ）に相当し、日常的な表現で言えば「〜かつ〜」のように、すべての条件を満たす場合のみバリデーションが通ります。

anyOf

oneOf

論理比較表

キーワード	論理演算	条件要件	主な用途
`allOf`	AND	すべての条件を同時に満たす必要がある	継承・拡張
`anyOf`	OR	いずれか1つ以上の条件を満たす必要がある	任意の組み合わせ
`oneOf`	XOR	ちょうど1つの条件のみを満たす必要がある	排他的選択

Apidogでの利用方法

1. ビジュアルエディタを利用する場合

Step 1: データスキーマの作成

プロジェクト内で「Schema」をクリックし、「新しいSchema」を選択します。

Step 2: スキーマコンポジションの追加

データスキーマ編集パネルで型を選択する際、「Schema Composition」をクリックし、oneOf、anyOf、allOfから選択します。各サブスキーマごとに具体的なデータ構造を定義してください。

2. JSON Schemaコードエディタを利用する場合

データスキーマ編集パネルで直接JSON Schemaコードを編集し、これらの論理的なコンポジションパターンを定義することも可能です。

APIドキュメントでの活用

リクエストパラメータの定義

endpointのリクエストパラメータを定義する際、これらのコンポジションパターンを活用することで、複雑なパラメータ構造を表現できます。

API編集画面に入ります。

「Request Parameters」セクションでBodyを選択し、JSONタイプを指定します。

データ構造内で「Reference Schema」をクリックするか、ビジネスロジックに応じて適切な「Schema Composition」を選択、またはカスタムJSON Schemaを定義します。

レスポンスデータの定義

同様に、レスポンスデータにもこれらのスキーマコンポジションを利用できます。

「Response」セクションでレスポンス例を追加します。

スキーマコンポジションを用いて、さまざまなレスポンス形式を表現します。

実践的な利用例

allOfの例（AND演算）

allOfを利用すると、複数のデータスキーマを組み合わせ、すべての条件を同時に満たす必要があります。例えば「ユーザー情報は基本情報かつ連絡先情報を含む必要がある」といったケースです。

{
  "allOf": [
    {
      "description": "基本ユーザー情報",
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    },
    {
      "description": "連絡先情報", 
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      },
      "required": ["email"]
    }
  ]
}

結果： 最終的なデータにはid、name、emailフィールドが必須となり、phoneは任意となります。各サブスキーマの制約が統合されて適用されます。

anyOfの例（OR演算）

anyOfを使うことで、複数のバリデーションパスから任意のものを選択できます。例えば「ユーザーはユーザー名/パスワードまたはメールアドレス/パスワードまたは電話番号/認証コードでログインできる」といったケースです。

{
  "type": "object",
  "properties": {
    "login": {
      "anyOf": [
        {
          "description": "ユーザー名/パスワードでのログイン",
          "properties": {
            "username": { "type": "string" },
            "password": { "type": "string" }
          },
          "required": ["username", "password"]
        },
        {
          "description": "メールアドレス/パスワードでのログイン",
          "properties": {
            "email": { "type": "string", "format": "email" },
            "password": { "type": "string" }
          },
          "required": ["email", "password"]
        },
        {
          "description": "電話番号/認証コードでのログイン",
          "properties": {
            "phone": { "type": "string" },
            "verifyCode": { "type": "string" }
          },
          "required": ["phone", "verifyCode"]
        }
      ]
    }
  }
}

結果： ユーザーは、いずれか1つまたは複数のログイン方法の情報を入力できます。1つでも条件を満たせばバリデーションが通ります。

oneOfの例（XOR演算）

oneOfを利用すると、ユーザーは支払い方法を1つだけ選択でき、複数を同時に指定することはできません。例えば「支払い方法はクレジットカードXORPayPalXOR銀行振込 ― いずれか1つのみ選択可能」のようなケースです。

{
  "type": "object", 
  "properties": {
    "payment": {
      "oneOf": [
        {
          "description": "クレジットカード決済",
          "type": "object",
          "properties": {
            "type": { "const": "credit_card" },
            "cardNumber": { "type": "string" },
            "expiryDate": { "type": "string" }
          },
          "required": ["type", "cardNumber", "expiryDate"],
          "additionalProperties": false
        },
        {
          "description": "PayPal決済", 
          "type": "object",
          "properties": {
            "type": { "const": "paypal" },
            "email": { "type": "string", "format": "email" }
          },
          "required": ["type", "email"],
          "additionalProperties": false
        },
        {
          "description": "銀行振込",
          "type": "object", 
          "properties": {
            "type": { "const": "bank_transfer" },
            "accountNumber": { "type": "string" },
            "routingNumber": { "type": "string" }
          },
          "required": ["type", "accountNumber", "routingNumber"],
          "additionalProperties": false
        }
      ]
    }
  }
}

結果： ユーザーは支払い方法を1つだけ選択しなければならず、複数同時や未選択は許可されません。

コンポジションパターンを選択する際は、まずビジネスロジックを明確にしましょう：

複数スキーマの結合・継承が必要な場合 → allOf（AND演算）

柔軟な選択肢が必要な場合 → anyOf（OR演算）

排他的な選択が必要な場合 → oneOf（XOR演算）

OpenAPIにおけるoneOf / allOf / anyOfの使い方

基本概念#

論理比較表#

Apidogでの利用方法#

1. ビジュアルエディタを利用する場合#

2. JSON Schemaコードエディタを利用する場合#

APIドキュメントでの活用#

リクエストパラメータの定義#

レスポンスデータの定義#

実践的な利用例#

allOfの例（AND演算）#

anyOfの例（OR演算）#

oneOfの例（XOR演算）#