oneOf, allOf, anyOf

oneOf, anyOf, dan allOf adalah kata kunci dalam spesifikasi JSON Schema yang digunakan untuk mendefinisikan struktur data komposit. Pada dasarnya, kata kunci tersebut merupakan operator logis yang diterapkan pada validasi data. Apidog sepenuhnya mendukung fitur JSON Schema ini, membantu Anda membuat dokumentasi API dan aturan validasi data yang lebih akurat.

Konsep Dasar

allOf

allOf berarti data harus secara bersamaan memenuhi semua kondisi subschema, setara dengan operasi AND dalam operasi logis. Seperti ungkapan "baik... maupun..." dalam bahasa sehari-hari, semua kondisi harus terpenuhi secara bersamaan agar validasi berhasil.

anyOf

oneOf

Tabel Perbandingan Logika

Kata Kunci	Operasi Logis	Persyaratan Kondisi	Kasus Penggunaan Umum
`allOf`	AND	Harus memenuhi semua kondisi secara bersamaan	Pewarisan, ekstensi
`anyOf`	OR	Harus memenuhi setidaknya satu kondisi	Kombinasi opsional
`oneOf`	XOR	Harus memenuhi tepat satu kondisi	Pilihan yang saling eksklusif

Penggunaan di Apidog

1. Menggunakan Editor Visual

Langkah 1: Buat Skema Data

Di proyek Anda, klik "Schemas", lalu "New Schema".

Langkah 2: Tambahkan Komposisi Skema

Di panel pengeditan skema data, saat memilih tipe, klik "Schema Composition" dan pilih oneOf, anyOf, atau allOf. Definisikan struktur data spesifik untuk setiap subschema.

2. Menggunakan Editor Kode JSON Schema

Anda juga dapat langsung mengedit kode JSON Schema di panel pengeditan skema data untuk mendefinisikan pola komposisi logis ini.

Penerapan dalam Dokumentasi API

Definisi Parameter Permintaan

Saat mendefinisikan parameter permintaan endpoint, Anda dapat menggunakan pola komposisi ini untuk mendeskripsikan struktur parameter yang kompleks:

Masuk ke halaman pengeditan API.

Di bagian "Request Parameters", pilih Body dan pilih tipe JSON.

Dalam struktur data, klik "Reference Schema", atau pilih "Schema Composition" yang sesuai berdasarkan logika bisnis, atau definisikan JSON Schema kustom.

Definisi Data Respons

Demikian pula, Anda dapat menggunakan komposisi skema ini dalam data respons:

Di bagian "Response", tambahkan contoh respons.

Gunakan komposisi skema untuk mendeskripsikan berbagai format respons.

Contoh Penggunaan Praktis

Contoh allOf (Operasi AND)

Menggunakan allOf memungkinkan Anda menggabungkan beberapa skema data, yang mengharuskan data memenuhi semua kondisi secara bersamaan. Ini seperti mengatakan "informasi pengguna harus mencakup informasi dasar AND informasi kontak":

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

Hasil: Data akhir harus berisi field id, name, dan email, dengan phone bersifat opsional. Semua batasan dari subschema digabungkan dan dijalankan, seperti ditunjukkan di bawah ini:

Contoh anyOf (Operasi OR)

Menggunakan anyOf menyediakan beberapa jalur validasi opsional - pengguna dapat memilih satu atau beberapa metode. Ini seperti mengatakan "pengguna dapat login melalui username/password OR email/password OR phone/verification code":

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

Hasil: Pengguna dapat memberikan informasi untuk satu atau beberapa metode login, selama setidaknya satu metode memenuhi persyaratan validasi, seperti ditunjukkan di bawah ini:

Contoh oneOf (Operasi XOR)

Menggunakan oneOf memastikan bahwa pengguna hanya dapat memilih satu metode pembayaran dan tidak dapat memberikan beberapa metode secara bersamaan. Ini seperti mengatakan "metode pembayaran harus kartu kredit XOR PayPal XOR transfer bank - tepat salah satu dari opsi ini":

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

Hasil: Pengguna harus memilih tepat satu metode pembayaran - mereka tidak dapat memberikan beberapa metode secara bersamaan, dan juga tidak dapat tidak memberikan metode apa pun, seperti ditunjukkan di bawah ini:

Praktik Terbaik

Saat memilih pola komposisi, pertama-tama klarifikasi logika bisnis Anda:

Perlu menggabungkan/mewarisi beberapa skema → Gunakan allOf (operasi AND)

Perlu kombinasi opsional yang fleksibel → Gunakan anyOf (operasi OR)

Perlu pilihan saling eksklusif yang ketat → Gunakan oneOf (operasi XOR)

Konsep Dasar#

Tabel Perbandingan Logika#

Penggunaan di Apidog#

1. Menggunakan Editor Visual#

2. Menggunakan Editor Kode JSON Schema#

Penerapan dalam Dokumentasi API#

Definisi Parameter Permintaan#

Definisi Data Respons#

Contoh Penggunaan Praktis#

Contoh allOf (Operasi AND)#

Contoh anyOf (Operasi OR)#

Contoh oneOf (Operasi XOR)#

Praktik Terbaik#