Parameter API seringkali memiliki struktur yang kompleks, dengan satu endpoint mendukung berbagai kombinasi parameter yang berbeda. Misalnya, sebuah endpoint login mungkin mendukung autentikasi nama pengguna-kata sandi, autentikasi email-kata sandi, atau kode verifikasi nomor telepon. Endpoint pembayaran dapat menawarkan berbagai metode seperti kartu kredit, WeChat Pay, atau Alipay, masing-masing memerlukan bidang yang berbeda.
Pendekatan dokumentasi API tradisional seringkali hanya mencantumkan semua bidang yang mungkin dan menggunakan deskripsi teks seperti "pilih bidang yang berbeda berdasarkan skenario yang berbeda." Pendekatan ini tidak tepat maupun ramah pengembang, seringkali menyebabkan kebingungan. Apidog mendukung fitur oneOf, anyOf, dan allOf dari JSON Schema, memungkinkan Anda untuk secara akurat mendeskripsikan struktur data komposit yang kompleks ini dalam dokumentasi API Anda.
Memahami Tiga Mode Kombinasi
Dalam JSON Schema, oneOf, anyOf, dan allOf digunakan untuk menggabungkan beberapa sub-skema, tetapi mereka memiliki arti logis yang berbeda:
- allOf: Menggabungkan beberapa aturan, mengharuskan semua cocok
- anyOf: Setidaknya satu kecocokan diperlukan, beberapa kecocokan dapat diterima
- oneOf: Harus cocok dengan tepat satu skema, kecocokan nol atau beberapa skema akan gagal
Mengatur Mode Kombinasi di Apidog
Apidog menyediakan dua cara untuk menggunakan mode kombinasi ini:
Pendekatan Editor Visual
Metode pertama menggunakan panel pengeditan visual. Dalam proyek Anda, klik "Model Data" untuk membuat model baru, lalu temukan "Mode Kombinasi" dalam pilihan tipe. Pilih mode oneOf, anyOf, atau allOf yang dibutuhkan, lalu definisikan struktur data spesifik untuk setiap sub-skema.
Editor Kode JSON Schema
Pendekatan kedua melibatkan pengeditan langsung kode JSON Schema. Di panel pengeditan model data, Anda dapat beralih ke mode kode dan menulis JSON Schema secara langsung untuk mendefinisikan pola kombinasi logis ini. Metode ini lebih langsung bagi pengembang yang akrab dengan JSON Schema.
Menerapkan Pola Ini di Endpoint API
Setelah Anda mendefinisikan model data Anda, Anda dapat menggunakannya dalam dokumentasi API Anda. Saat mengedit parameter permintaan antarmuka, pilih tipe Body sebagai JSON, lalu di bagian struktur data, Anda dapat mereferensikan "Model Data" yang baru saja Anda buat, atau langsung memilih "Mode Kombinasi" untuk mendefinisikan struktur parameter yang kompleks.
Prinsip yang sama berlaku untuk definisi data respons. Saat menambahkan contoh respons di bagian respons pengembalian, Anda dapat menggunakan mode kombinasi untuk mendeskripsikan format respons untuk skenario yang berbeda. Dengan cara ini, pengembang dapat dengan jelas memahami struktur data apa yang akan dikembalikan dalam situasi yang berbeda.
Kasus Penggunaan Dunia Nyata
allOf: Menggabungkan Beberapa Struktur
allOf menggabungkan beberapa struktur bersama - ini bukan tentang pilihan, tetapi tentang penumpukan. allOf tidak mengubah hierarki bidang; semua bidang berakhir dalam objek yang sama. Ini hanya menumpuk beberapa aturan pada data yang sama. Anggap saja sebagai "AND logis" - semua batasan sub-struktur harus dipenuhi.
Misalnya, JSON Schema ini:
{
"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"]
}
]
}
Skema ini berarti: data akhir harus secara bersamaan memenuhi struktur "informasi pengguna dasar" dan "informasi kontak".
Dengan kata lain, body permintaan harus menyertakan id, nama, dan email, sedangkan telepon bersifat opsional.
Data valid:
{
"id": 1001,
"name": "John Doe",
"email": "john@example.com",
"phone": "1-800-000-0000"
}
Data tidak valid:
{
"id": 1001,
"name": "John Doe"
}
Ini tidak memiliki bidang email yang wajib dan tidak memenuhi struktur kedua.
Pendekatan ini cocok untuk memecah objek kompleks. Informasi pengguna, detail pesanan, item konfigurasi, dll., semuanya dapat dibagi menjadi struktur independen berdasarkan modul fungsional, lalu digabungkan menggunakan allOf. Antarmuka lain yang membutuhkan sebagian dari struktur ini dapat mereferensikannya secara langsung tanpa definisi yang berlebihan.
anyOf: Memenuhi Setidaknya Satu Kondisi
anyOf mencantumkan beberapa struktur yang mungkin, dan data dianggap valid selama sesuai dengan setidaknya salah satunya. Ini tidak peduli apakah beberapa kondisi terpenuhi, juga tidak memerlukan pencocokan yang unik.
Misalnya, bidang pengenal mungkin berupa email atau nomor telepon. Kedua format ini sangat berbeda, tetapi keduanya termasuk dalam kategori "kredensial login pengguna".
Anda dapat menggunakan anyOf untuk dengan jelas menyatakan maksud "bisa A atau B" ini:
{
"type": "object",
"properties": {
"identifier": {
"description": "User identifier: can be email or phone number",
"anyOf": [
{
"title": "Email format",
"description": "Must be a valid email address",
"type": "string",
"format": "email"
},
{
"title": "Phone format",
"description": "Must be a valid international phone number",
"type": "string",
"pattern": "^\\+?[1-9]\\d{1,14}$"
}
]
},
"password": {
"type": "string",
"minLength": 6,
"description": "Login password, at least 6 characters"
}
},
"required": ["identifier", "password"],
"description": "User login request parameters"
}
Struktur ini berarti: pengenal adalah string yang dianggap valid selama memenuhi format email atau format nomor telepon.
Data valid:
{
"identifier": "test@example.com",
"password": "123456"
}
{
"identifier": "+1-800-000-0000",
"password": "123456"
}
Data tidak valid:
{
"identifier": "abc",
"password": "123456"
}
"abc" bukan email maupun format nomor telepon yang valid, tidak memenuhi salah satu kondisi.
oneOf: Pilih Tepat Satu Opsi
oneOf mencantumkan beberapa struktur yang mungkin, dan data harus sesuai dengan tepat salah satunya. Ini menekankan eksklusivitas - Anda hanya dapat memilih satu, tidak lebih, tidak kurang.
Misalnya, metode pembayaran: untuk menyelesaikan pembayaran, pengguna harus memilih salah satu dari kartu kredit, WeChat Pay, atau Alipay, tetapi tidak dapat menggunakan dua metode secara bersamaan, juga tidak dapat memilih tidak sama sekali. Anda dapat mendefinisikan logika "pilihan tunggal" ini menggunakan oneOf:
{
"properties": {
"paymentMethod": {
"description": "Payment method, must choose exactly one",
"oneOf": [
{
"title": "Credit Card Payment",
"description": "Pay with credit card, requires card number and expiry date",
"type": "object",
"properties": {
"type": { "const": "credit_card" },
"cardNumber": { "type": "string" },
"expiryDate": { "type": "string" }
},
"required": ["type", "cardNumber", "expiryDate"],
"additionalProperties": false
},
{
"title": "WeChat Pay",
"description": "Pay through WeChat, requires user's openid",
"type": "object",
"properties": {
"type": { "const": "wechat" },
"openid": { "type": "string" }
},
"required": ["type", "openid"],
"additionalProperties": false
},
{
"title": "Alipay Payment",
"description": "Pay through Alipay, requires account ID",
"type": "object",
"properties": {
"type": { "const": "alipay" },
"accountId": { "type": "string" }
},
"required": ["type", "accountId"],
"additionalProperties": false
}
]
}
}
}
Definisi ini berarti: paymentMethod adalah objek yang hanya dapat cocok dengan salah satu dari tiga sub-struktur.
Contoh valid:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123456"
}
}
{
"paymentMethod": {
"type": "credit_card",
"cardNumber": "4111111111111111",
"expiryDate": "12/25"
}
}
Contoh tidak valid:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123",
"accountId": "2088102"
}
}
Meskipun tipe adalah "wechat", keberadaan accountId mungkin menyebabkannya cocok dengan beberapa struktur, menyebabkan oneOf gagal. Menambahkan "additionalProperties": false mencegah kebingungan ini (artinya tidak ada bidang tambahan yang diizinkan), memastikan setiap struktur hanya mengizinkan bidang yang didefinisikan sendiri. Apidog mendukung konfigurasi visual untuk additionalProperties.
Ketika Anda perlu membuat pilihan eksklusif antara beberapa tipe yang berbeda, oneOf adalah cara paling langsung dan andal untuk menyatakannya.
Memilih Mode Kombinasi yang Tepat
Pilihan mode kombinasi terutama tergantung pada logika bisnis Anda:
- Gunakan allOf ketika Anda perlu menggabungkan dan mewarisi beberapa pola
- Gunakan anyOf ketika Anda membutuhkan kombinasi opsional yang fleksibel
- Gunakan oneOf ketika Anda membutuhkan pilihan eksklusif yang ketat
Memahami peran masing-masing memungkinkan dokumentasi API Anda untuk secara akurat mendeskripsikan struktur data yang kompleks, membuatnya segera jelas bagi pengguna antarmuka bagaimana cara mengirimkan parameter.
Kesimpulan
Dukungan JSON Schema Apidog yang komprehensif memberdayakan pengembang untuk membuat dokumentasi API yang tepat dan jelas bahkan untuk struktur parameter yang paling kompleks sekalipun. Dengan memanfaatkan kombinasi oneOf, anyOf, dan allOf, Anda dapat menghilangkan ambiguitas dan memberikan panduan yang sangat jelas kepada konsumen API.
Siap merasakan kekuatan dokumentasi API tingkat lanjut? Coba Apidog hari ini dan lihat betapa mudahnya mengelola parameter API yang kompleks dengan presisi dan kejelasan.