API parametreleri genellikle karmaşık yapılara sahiptir; tek bir uç nokta birden fazla farklı parametre kombinasyonunu destekleyebilir. Örneğin, bir oturum açma uç noktası kullanıcı adı-parola kimlik doğrulamasını, e-posta-parola kimlik doğrulamasını veya telefon numarası doğrulama kodlarını destekleyebilir. Ödeme uç noktaları, her biri farklı alanlar gerektiren kredi kartları, WeChat Pay veya Alipay gibi çeşitli yöntemler sunabilir.
Geleneksel API belgeleme yaklaşımları genellikle tüm olası alanları listeler ve "farklı senaryolara göre farklı alanları seçin" gibi metin açıklamaları kullanır. Bu yaklaşım ne kesin ne de geliştirici dostudur ve genellikle kafa karışıklığına yol açar. Apidog, JSON Şeması'nın `oneOf`, `anyOf` ve `allOf` özelliklerini destekleyerek bu karmaşık bileşik veri yapılarını API belgelerinizde doğru bir şekilde tanımlamanıza olanak tanır.
Üç Kombinasyon Modunu Anlamak
JSON Şemasında, `oneOf`, `anyOf` ve `allOf` birden fazla alt şemayı birleştirmek için kullanılır, ancak farklı mantıksal anlamlara sahiptirler:
- allOf: Birden fazla kuralı birleştirir, hepsinin eşleşmesini gerektirir
- anyOf: En az bir eşleşme gereklidir, birden fazla eşleşme kabul edilebilir
- oneOf: Tam olarak bir şemayla eşleşmelidir, sıfır veya birden fazla şemayla eşleşme başarısız olur
Apidog'da Kombinasyon Modlarını Ayarlama
Apidog, bu kombinasyon modlarını kullanmak için iki yol sunar:
Görsel Düzenleyici Yaklaşımı
İlk yöntem, görsel düzenleme panelini kullanır. Projenizde, yeni bir model oluşturmak için "Veri Modelleri"ne tıklayın, ardından tür seçiminde "Kombinasyon Modları"nı bulun. İhtiyaç duyulan `oneOf`, `anyOf` veya `allOf` modunu seçin, ardından her alt şema için belirli veri yapılarını tanımlayın.
JSON Şeması Kod Düzenleyicisi
İkinci yaklaşım, doğrudan JSON Şeması kodunu düzenlemeyi içerir. Veri modeli düzenleme panelinde, kod moduna geçebilir ve bu mantıksal kombinasyon desenlerini tanımlamak için doğrudan JSON Şeması yazabilirsiniz. Bu yöntem, JSON Şemasına aşina olan geliştiriciler için daha doğrudan bir yöntemdir.
Bu Desenleri API Uç Noktalarında Uygulama
Veri modellerinizi tanımladıktan sonra, bunları API belgelerinizde kullanabilirsiniz. Arayüz istek parametrelerini düzenlerken, Gövde türünü JSON olarak seçin, ardından veri yapısı bölümünde, yeni oluşturduğunuz "Veri Modelleri"ne başvurabilir veya karmaşık parametre yapılarını tanımlamak için doğrudan "Kombinasyon Modları"nı seçebilirsiniz.
Aynı prensip yanıt veri tanımları için de geçerlidir. Dönüş yanıtı bölümüne yanıt örnekleri eklerken, farklı senaryolar için yanıt formatlarını tanımlamak üzere kombinasyon modlarını kullanabilirsiniz. Bu sayede geliştiriciler, farklı durumlarda hangi veri yapısının döndürüleceğini net bir şekilde anlayabilirler.
Gerçek Dünya Kullanım Durumları
allOf: Birden Fazla Yapıyı Birleştirme
`allOf` birden fazla yapıyı bir araya getirir - bu bir seçim değil, bir yığma işlemidir. `allOf` alan hiyerarşisini değiştirmez; tüm alanlar aynı nesnede biter. Sadece aynı veri üzerinde birden fazla kuralı üst üste yığar. Bunu "mantıksal VE" olarak düşünün - tüm alt yapı kısıtlamaları karşılanmalıdır.
Örneğin, bu JSON Şeması:
{
"allOf": [
{
"description": "Temel kullanıcı bilgileri",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
},
{
"description": "İletişim bilgileri",
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"phone": { "type": "string" }
},
"required": ["email"]
}
]
}
Bu şema şu anlama gelir: nihai veri hem "temel kullanıcı bilgileri" hem de "iletişim bilgileri" yapılarını aynı anda karşılamalıdır.
Başka bir deyişle, istek gövdesi `id`, `name` ve `email` içermelidir, `phone` ise isteğe bağlıdır.
Geçerli veri:
{
"id": 1001,
"name": "John Doe",
"email": "john@example.com",
"phone": "1-800-000-0000"
}
Geçersiz veri:
{
"id": 1001,
"name": "John Doe"
}
Bu, gerekli `email` alanını içermez ve ikinci yapıyı karşılamaz.
Bu yaklaşım, karmaşık nesneleri bölmek için uygundur. Kullanıcı bilgileri, sipariş detayları, yapılandırma öğeleri vb. hepsi fonksiyonel modüllere göre bağımsız yapılara bölünebilir, ardından `allOf` kullanılarak birleştirilebilir. Bu yapıların bir kısmına ihtiyaç duyan diğer arayüzler, fazladan tanımlama yapmadan doğrudan bunlara başvurabilir.
anyOf: En Az Bir Koşulu Sağlama
`anyOf` birden fazla olası yapıyı listeler ve veri, bunlardan en az birine uygun olduğu sürece geçerli kabul edilir. Birden fazla koşulun karşılanıp karşılanmadığını umursamaz, ayrıca benzersiz eşleşme de gerektirmez.
Örneğin, bir tanımlayıcı alanı bir e-posta veya bir telefon numarası olabilir. Bu iki format belirgin şekilde farklıdır, ancak her ikisi de "kullanıcı oturum açma kimlik bilgileri" kategorisine aittir.
Bu "A veya B olabilir" niyetini açıkça ifade etmek için `anyOf` kullanabilirsiniz:
{
"type": "object",
"properties": {
"identifier": {
"description": "Kullanıcı tanımlayıcısı: e-posta veya telefon numarası olabilir",
"anyOf": [
{
"title": "E-posta formatı",
"description": "Geçerli bir e-posta adresi olmalıdır",
"type": "string",
"format": "email"
},
{
"title": "Telefon formatı",
"description": "Geçerli bir uluslararası telefon numarası olmalıdır",
"type": "string",
"pattern": "^\\+?[1-9]\\d{1,14}$"
}
]
},
"password": {
"type": "string",
"minLength": 6,
"description": "Oturum açma şifresi, en az 6 karakter"
}
},
"required": ["identifier", "password"],
"description": "Kullanıcı oturum açma isteği parametreleri"
}
Bu yapı şu anlama gelir: `identifier`, e-posta formatını veya telefon numarası formatını karşıladığı sürece geçerli kabul edilen bir dizedir.
Geçerli veri:
{
"identifier": "test@example.com",
"password": "123456"
}
{
"identifier": "+1-800-000-0000",
"password": "123456"
}
Geçersiz veri:
{
"identifier": "abc",
"password": "123456"
}
"abc" ne bir e-posta ne de geçerli bir telefon numarası formatıdır, koşulların hiçbirini karşılamaz.
oneOf: Tam Olarak Bir Seçenek Belirleyin
`oneOf` birden fazla olası yapıyı listeler ve veri, bunlardan tam olarak birine uygun olmalıdır. Dışlayıcılığı vurgular - yalnızca birini seçebilirsiniz, ne daha fazla ne de daha az.
Örneğin, ödeme yöntemleri: bir ödemeyi tamamlamak için kullanıcıların kredi kartı, WeChat Pay veya Alipay'den birini seçmesi gerekir, ancak aynı anda iki yöntem kullanamazlar veya hiçbirini seçemezler. Bu "tek seçenekli" mantığı `oneOf` kullanarak tanımlayabilirsiniz:
{
"properties": {
"paymentMethod": {
"description": "Ödeme yöntemi, tam olarak birini seçmelidir",
"oneOf": [
{
"title": "Kredi Kartı Ödemesi",
"description": "Kredi kartıyla ödeme, kart numarası ve son kullanma tarihi gerektirir",
"type": "object",
"properties": {
"type": { "const": "credit_card" },
"cardNumber": { "type": "string" },
"expiryDate": { "type": "string" }
},
"required": ["type", "cardNumber", "expiryDate"],
"additionalProperties": false
},
{
"title": "WeChat Pay",
"description": "WeChat aracılığıyla ödeme, kullanıcının openid'ini gerektirir",
"type": "object",
"properties": {
"type": { "const": "wechat" },
"openid": { "type": "string" }
},
"required": ["type", "openid"],
"additionalProperties": false
},
{
"title": "Alipay Ödemesi",
"description": "Alipay aracılığıyla ödeme, hesap kimliği gerektirir",
"type": "object",
"properties": {
"type": { "const": "alipay" },
"accountId": { "type": "string" }
},
"required": ["type", "accountId"],
"additionalProperties": false
}
]
}
}
}
Bu tanım şu anlama gelir: `paymentMethod`, üç alt yapıdan yalnızca birine eşleşebilen bir nesnedir.
Geçerli örnekler:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123456"
}
}
{
"paymentMethod": {
"type": "credit_card",
"cardNumber": "4111111111111111",
"expiryDate": "12/25"
}
}
Geçersiz örnek:
{
"paymentMethod": {
"type": "wechat",
"openid": "wx_123",
"accountId": "2088102"
}
}
Türü "wechat" olsa bile, `accountId`'nin varlığı birden fazla yapıyla eşleşmesine neden olabilir ve bu da `oneOf`'un başarısız olmasına yol açar. `"additionalProperties": false` eklemek bu karışıklığı önler (yani ek alanlara izin verilmez), her yapının yalnızca kendi tanımladığı alanlara izin vermesini sağlar. Apidog, `additionalProperties` için görsel yapılandırmayı destekler.
Birden fazla farklı tür arasında özel seçimler yapmanız gerektiğinde, `oneOf` bunu ifade etmenin en doğrudan ve güvenilir yoludur.
Doğru Kombinasyon Modunu Seçme
Kombinasyon modunun seçimi temel olarak iş mantığınıza bağlıdır:
- Birden fazla deseni birleştirmeniz ve devralmanız gerektiğinde allOf kullanın
- Esnek isteğe bağlı kombinasyonlara ihtiyacınız olduğunda anyOf kullanın
- Katı dışlayıcı seçimlere ihtiyacınız olduğunda oneOf kullanın
İlgili rollerini anlamak, API belgelerinizin karmaşık veri yapılarını doğru bir şekilde tanımlamasına olanak tanır ve arayüz kullanıcılarının parametreleri nasıl ileteceklerini anında netleştirir.
Sonuç
Apidog'un kapsamlı JSON Şeması desteği, geliştiricilerin en karmaşık parametre yapıları için bile hassas, net API belgeleri oluşturmasını sağlar. `oneOf`, `anyOf` ve `allOf` kombinasyonlarından yararlanarak belirsizliği ortadan kaldırabilir ve API tüketicilerine kristal netliğinde rehberlik sağlayabilirsiniz.
Gelişmiş API belgelemesinin gücünü deneyimlemeye hazır mısınız? Apidog'u bugün deneyin ve karmaşık API parametrelerini hassasiyet ve netlikle yönetmenin ne kadar kolaylaştığını görün.