Gelişen veri yapılarıyla sorunsuz bir şekilde entegre olan API'ler oluşturmak, API geliştirmede çok önemlidir. JSON Schema, API tanımı için yaygın olarak benimsenen bir standarttır ve OpenAPI ile birlikte veri yapılarını ve doğrulama kurallarını tanımlamak için sağlam bir çerçeve sağlar.
Bu çerçevede, oneOf, anyOf ve allOf anahtar kelimeleri, esnek ve uyarlanabilir API'ler oluşturmak için güçlü araçlar olarak ortaya çıkıyor. oneOf, tek bir veri yapısı için birden fazla geçerli şemayı belirtmeye yardımcı olur.
anyOf, bir veri yapısını diğer mevcut şemalara karşı doğrulamak için bir mekanizma sağlar. allOf, birden fazla şema seçeneğini tek bir doğrulama kuralında birleştirerek bir veri yapısının belirtilen tüm kısıtlamalara uymasını sağlar. Apidog, API'lerin çeşitli veri ihtiyaçlarına sorunsuz bir şekilde uyum sağlamasına yardımcı olur.
oneOf Nedir?
"oneOf" terimi, JSON şemaları gibi şema tanımları bağlamında kullanılan bir yapı veya anahtar kelimeyi ifade eder. "oneOf", birden fazla alt şema belirtmenize olanak tanır ve şemanın geçerli bir örneği, bu alt şemaların tam olarak birinin kısıtlamalarına uymalıdır. Örneğin, bir kişinin yetişkin veya çocuk olabileceği bir kişi için bir JSON şeması düşünün.
"oneOf" anahtar kelimesi, yetişkinler ve çocuklar için birer tane olmak üzere iki alt şema belirtebilir. Doğrulanmakta olan belge, yetişkin veya çocuk şemasının kısıtlamalarını karşılamalı, ancak her ikisini birden karşılamamalıdır. İşte bir JSON şemasında nasıl görüneceği.
{
"type": "object",
"oneOf": [
{
"properties": {
"age": { "type": "integer", "minimum": 18 }
},
"required": ["age"]
},
{
"properties": {
"age": { "type": "integer", "maximum": 17 }
},
"required": ["age"]
}
]
}
Bu örnekte, "oneOf" anahtar kelimesi, yetişkinler ve çocuklar için iki alt şema tanımlamak için kullanılır. Doğrulanmakta olan belge, yetişkin veya çocuk şemasının kısıtlamalarını karşılamalı, ancak her ikisini birden karşılamamalıdır. "age" özelliği, hangi alt şemanın uygulanması gerektiğini belirlemek için bir ayrıştırıcıdır.
Bu esneklik, farklı koşullara bağlı olarak bir JSON belgesi için çeşitli geçerli yapılar olduğunda faydalıdır. "oneOf" anahtar kelimesi, tanımlanan alt şemalar arasında karşılıklı dışlamayı garanti ederek, geçerli bir örneğin yalnızca belirtilen yapılardan birine uymasını sağlar. Bu yetenek, "oneOf"u karmaşık veri modellerini doğru bir şekilde tanımlamak ve çeşitli senaryolarda veri bütünlüğünü korumak için değerli bir araç haline getirir.
anyOf Nedir?
“anyOf" anahtar kelimesi, doğrulanmış örneğin en az bir belirtilen alt şemaya uyması gereken bir şema tanımlamak için kullanılan başka bir yapıdır. Yalnızca bir alt şemaya özel olarak uyulmasını zorunlu kılan "oneOf"un aksine, "anyOf", örneğin belirtilen alt şemaların en az birinin kısıtlamalarını karşılamasına izin vererek daha fazla esneklik sunar.
"anyOf"un faydalı olabileceği pratik bir senaryo düşünelim. Bazıları yetişkin, diğerleri öğrenci olan bireyleri temsil eden JSON verileriyle çalıştığınızı hayal edin. Hem yetişkinlerin hem de öğrencilerin farklı özellikleri vardır ve her iki durumu da barındıran bir şema oluşturmak istersiniz.
"anyOf" anahtar kelimesi, bu esnekliği ifade etmenizi sağlar ve JSON belgesinin yetişkinler veya öğrenciler için olan şemaya uyması durumunda geçerli olmasına izin verir. İşte bu örneğin bir JSON şemasında nasıl temsil edildiği.
{
"type": "object",
"anyOf": [
{
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["name", "age"]
},
{
"properties": {
"name": { "type": "string" },
"grade": { "type": "string", "enum": ["A", "B", "C"] }
},
"required": ["name", "grade"]
}
]
}
Bu örnekte, "anyOf" anahtar kelimesi, yetişkinler ve öğrenciler için iki alt şema tanımlamak için kullanılır. JSON belgesi, yetişkin veya öğrenci şemasının kısıtlamalarını karşılıyorsa geçerli kabul edilir. Bu, aynı genel şema içinde çeşitli veri yapılarının esnek bir şekilde temsil edilmesine izin vererek, "anyOf"u çeşitli veri senaryolarını ele almak için güçlü bir araç haline getirir.
OneOf vs anyof: Z şemasında fark nedir?
Z Şemasında, OneOf ve AnyOf her ikisi de birden fazla şema tanımlamak için kullanılır, ancak farklı amaçlara hizmet ederler.
OneOf:
OneOf, tanımlanan şemalardan tam olarak birinin eşleşmesi gerektiğinde kullanılır.
Verilerin yalnızca belirtilen şemalardan biriyle doğrulandığından emin olur.
Örnek:
{
"OneOf": [
{"type": "string"},
{"type": "number"}
]
}
Bu şema, verilerin ya bir dize ya da bir sayı olmasını sağlar, ancak her ikisi birden olamaz.
AnyOf:
AnyOf, tanımlanan şemalardan herhangi birinin veya daha fazlasının eşleşebileceği durumlarda kullanılır.
Verilerin birden fazla belirtilen şemaya karşı doğrulanmasına izin verir.
Örnek:
{
"AnyOf": [
{"type": "string"},
{"type": "number"}
]
}
allOf Nedir?
JSON Şemasındaki "allOf" anahtar kelimesi, doğrulanmış örneğin belirtilen tüm alt şemalara uyması gereken bir şema tanımlar. Esasen, alt şemalar için mantıksal bir VE işlemi temsil eder. Bu, doğrulanmış JSON belgesinin "allOf" altında listelenen her alt şemanın kısıtlamalarını karşılaması gerektiği anlamına gelir. İşte bir örnek:
{
"allOf": [
{
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 18 }
},
"required": ["name", "age"]
},
{
"properties": {
"hasDegree": { "type": "boolean", "default": true }
},
"required": ["hasDegree"]
}
]
}
Bu örnekte, "allOf" anahtar kelimesi iki alt şemayı birleştirir. İlk alt şema, belirli kısıtlamalarla bir ad ve yaş dahil olmak üzere yetişkinler için özellikleri tanımlar. İkinci alt şema, bu durumda varsayılan değeri true olan bir boolean özelliği olan "hasDegree" derecesi olan bireyler için bir özellik sunar. "allOf"un birleşik etkisi, doğrulanmış JSON belgesinin her iki kısıtlamaya da uyması gerektiğidir. Bir adı, yaşı (ilk alt şemayı karşılayan) olmalı ve ayrıca "hasDegree" özelliğini (ikinci alt şemayı karşılayan) içermelidir.
"allOf" anahtar kelimesi, birden fazla alt şemadan özellikleri ve kısıtlamaları kapsayan, doğrulanmış örneğin belirtilen tüm koşulları karşılamasını sağlayan bir şema oluştururken kullanışlıdır. Bu mantıksal VE işlemi, belirtilen alt şemaların en az birini veya tam olarak birini karşılamada esneklik sağlayan "anyOf" ve "oneOf"tan farklıdır.
Apidog Nedir?
Apidog , API test etme, hata ayıklama, tasarım, sahtesini oluşturma ve dokümantasyonu basitleştiren çok yönlü bir API entegrasyon platformudur. Kullanıcı dostu bir arayüz, işbirliğine dayalı araçlar ve kapsamlı API değerlendirmeleri için özellikler sunar.
Apidog, API yanıtlarını özelleştirilebilir düzenlerle belgelemekte ve ekipler içinde işbirliği çabalarını kolaylaştırmakta mükemmeldir. Test araçları, görsel onay eklemeyi ve test dalı oluşturmayı sağlar. Platform ayrıca API etkinliğini izlemeye yardımcı olur ve geliştirme sırasında komut dosyası yazma ihtiyacını ortadan kaldıran verimli sahtesini oluşturma yetenekleri sağlar.
oneOf, anyOf ve allOf ile Apidog JSON şemaları
Artık JSON şemalarının ne olduğunu ve yapıları içinde oneOf, anyOf ve allOf'u nasıl kullandıklarını bildiğinize göre, bunları Apidog'da tanımlayacağız. Bu şemaları Apidog'da verimli bir şekilde oluşturmak için, sisteminizde Apidog'un yüklü olduğundan veya Apidog hizmetlerini çevrimiçi kullanmak için bir hesabınız olduğundan emin olun.
oneOf Nasıl Oluşturulur
- HTTP türü ile Apidog'da yeni bir proje oluşturun.
2. Yeni Şema düğmesine tıklayarak yeni bir Şema oluşturun.
3. JSON'dan Oluştur seçeneğine tıklayın ve JSON şeması seçeneğine gidin.
4. Aşağıdaki kodu düzenleyiciye girin.
{
"title": "Ödeme Şeması Örneği",
"type": "object",
"properties": {
"payment": {
"oneOf": [
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": ["amount", "currency"]
},
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"cardDetails": {
"type": "object",
"properties": {
"cardNumber": {
"type": "string"
},
"expirationDate": {
"type": "string"
},
"cvv": {
"type": "string"
}
},
"required": ["cardNumber", "expirationDate", "cvv"]
}
},
"required": ["amount", "currency", "cardDetails"]
}
]
}
},
"required": ["payment"]
}
5. Şemanızı kaydedin.
oneOf şemanız başarıyla oluşturuldu!
anyOf Nasıl Oluşturulur
oneOf için yukarıdaki tüm adımları izleyin, ancak anyOf şemanız için yapacağınız tek değişiklik kodu değiştirmektir. Şemanızı oluşturmak için düzenleyiciye aşağıdaki kodu girin.
{
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
}
},
"required": ["street", "city", "state", "zip"]
},
{
"type": "object",
"properties": {
"country": {
"type": "string"
}
},
"required": ["country"]
}
]
}
},
"required": ["address"]
}
allOf
oneOf için yukarıdaki tüm adımları izleyin, ancak allOf şemanız için yapacağınız tek değişiklik kodu değiştirmektir. Şemanızı oluşturmak için düzenleyiciye aşağıdaki kodu girin.
{
"type": "object",
"properties": {
"product": {
"allOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["name", "description"]
},
{
"type": "object",
"properties": {
"price": {
"type": "number"
},
"stock": {
"type": "integer"
}
},
"required": ["price", "stock"]
}
]
}
},
"required": ["product"]
}
Apidog ile Şema Oluşturmanın Faydaları
Apidog ile JSON şemalarınızı oluşturduktan sonra yapabileceğiniz birkaç kullanışlı şey var. Bazı faydalar aşağıda belirtilmiştir.
API Dokümantasyonu
API uç noktalarınızın veri yapılarının ve doğrulama kurallarının net ve kapsamlı açıklamalarını sağlamak için JSON Şemanızı API dokümantasyonunuza entegre edebilirsiniz. Bu, geliştiricilerin anlayışını geliştirir ve API kullanımında hata riskini azaltır.
Kod oluşturma
JSON Şemanızdan otomatik olarak istemci kitaplıkları ve sunucu tarafı kodu oluşturmak için Apidog'un kod oluşturma yetenekleri gibi araçları kullanabilirsiniz. Bu, geliştirme sürecini kolaylaştırır ve API tanımınız ile uygulaması arasında tutarlılık sağlar.
Veri doğrulama ve hata işleme
Gelen API isteklerini ve yanıtlarını doğrulamak, verilerin tanımlanan yapıya ve kısıtlamalara uygun olmasını sağlamak için JSON Şema doğrulama kitaplıklarını kullanabilirsiniz. Bu, sisteminize geçersiz verilerin girmesini engellemeye yardımcı olur ve uygulama hataları riskini azaltır.
API testi
API uç noktalarınız için test senaryoları oluşturmak ve test için sahte sunucular oluşturmak için JSON Şemayı kullanabilirsiniz. Bu, kapsamlı API testini kolaylaştırır ve API'nizin amaçlandığı gibi çalıştığından emin olur.
API tasarımı
Yeni veri gereksinimlerini ve kullanım kalıplarını karşılamak için API'niz geliştikçe JSON Şemanızı sürekli olarak iyileştirebilirsiniz. Bu, API'nizin değişen taleplere karşı esnek ve uyarlanabilir kalmasını sağlar.
Sonuç
Sonuç olarak, JSON şemalarını Apidog ile entegre etmek, API'ler için dokümantasyon sürecini büyük ölçüde geliştirebilir. JSON Şema, JSON verilerinin yapısını ve kısıtlamalarını açıklamanın standartlaştırılmış bir yolunu sağlar ve API dokümantasyon araçlarıyla entegre edildiğinde, dokümantasyonun beklenen istek ve yanıt biçimlerini doğru bir şekilde yansıtmasını sağlar.
Apidog, JSON şemalarından yararlanan özellikleri destekler. Örneğin, tanımlanan şemalara göre otomatik olarak dokümantasyon oluşturabilir ve API geliştikçe dokümantasyonun güncel tutulmasını kolaylaştırabilir.
