Schema, örnek ve doğrulama kuralları

Schema, verinin biçimini ve kabul edilebilir değerlerini tanımlar. Örneğin sipariş miktarının pozitif bir integer, müşteri kodunun zorunlu bir string olduğunu söyleyebilirsiniz. Aynı modeli birden çok yerde kullanmak için ortak schema oluşturun.

Bu ilişkiyi çalışan kodda görmek için ortak hata projesini açın. Üç işlem tek modeli kullanır; şemayı değiştirmekle gerçek yanıtı değiştirmek arasındaki farkı küçük bir deneyle görebilirsiniz.

Schema, isteği gönderenle işleyen tarafın veri anlaşmasıdır. JSON’un geçerli yazılmış olması yeterli değildir: {"quantity":"2"} geçerli JSON’dur, fakat miktarı integer bekleyen bir model için yanlıştır. {"quantity":2} ise sayısal değer taşır. Bir müşterinin gerçekten mevcut olup olmadığını veya stok yeterliliğini schema’dan öğrenemezsiniz; bu kontroller ilgili veriye erişen iş akışında yapılır.

Modeli nerede tanımlamalısınız?

Inline schema, tek bir request veya response içinde tanımlanır. Küçük ve yalnızca o işlemde kullanılan veriler için uygundur. Ortak schema, Components → Schemas altında adlandırılır; işlemler onu $ref ile kullanır. Örneğin OrderRequest, sipariş oluşturma ve önizleme girdilerinin ortak modeli olabilir.

Request ve response modelini ayrı tutmanız, gönderilebilen ve geri dönen alanları açıkça anlatır. İstemci customerId ve quantity gönderirken servis total hesaplayabilir. Response’a total alanı eklemek hesabı oluşturmaz; hesabı route’ta yaparsınız.

Ortak model oluşturun

1. API design ağacındaki Add → Schema seçin.
2. Schema name alanına OrderRequest yazın.
3. Türü object seçin.
4. Add property to OrderRequest ile aşağıdaki alanları ekleyin.

5. Alan satırını açıp sınırlamaları girin. Modelin üretilmiş örneğini kontrol edin.
6. Operation’ın Request body sekmesinde JSON media type’ının type listesinden OrderRequest seçin.
7. Save, ardından çalışan proje için Reload yapın.

Alan satırını genişlettiğinizde o türün sınırları görünür. Görselde quantity zorunlu bir integer’dır; 1 altındaki veya 100 üstündeki değerler bu request modeline uymaz. İş kuralının daha dar bir sınır getirmesi ayrıca mümkündür.

Source’taki karşılığı şöyledir:

{
  "type": "object",
  "required": ["customerId", "quantity"],
  "additionalProperties": false,
  "properties": {
    "customerId": {"type": "string", "minLength": 1},
    "quantity": {"type": "integer", "minimum": 1, "maximum": 100},
    "note": {"type": "string", "maxLength": 200}
  }
}

Bu örnekte additionalProperties: false tanımlı olmayan alanları reddeder. Formdaki Allows additional properties seçeneği bunu kontrol eder. İş ihtiyacınız ek alanları kabul ediyorsa bu kısıtlamayı koymayın.

Kuralları seçin

Formda görmediğiniz tanımlar için Schema JSON veya Source kullanın. JSON alanını değiştirdiğinizde Apply schema ya da ilgili Apply … JSON düğmesiyle uygulayın. Geçersiz veya uygulanmamış değer Save işlemini engeller. Sayı alanını boşaltmak kuralı kaldırır.

Minimum veya Maximum gibi bir sayı yazdıktan sonra Tab ile alandan çıkın; değer alanı terk ettiğinizde modele uygulanır. Pending schema edits görüyorsanız sayı alanından çıkmayı, geçersiz değeri düzeltmeyi veya ilgili Discard seçeneğini kontrol edin. Ardından üstteki Save ile dosyayı kaydedin.

Required alanın bulunmasını, Nullable ise değer olarak null kabulünü belirler. Bunlar farklıdır: bir alan bulunması zorunlu olup null kabul edebilir. Kullanılan OpenAPI sürümünün nullable gösterimini koruyun; Form bu seçimi sürüme göre yazar.

Yok, null ve boş değer farklıdır

note alanının string olduğunu varsayın:

Required tek başına boş metni engellemez. Boş olmayan bir değer için minLength: 1 kullanın. Yalnızca boşluklardan oluşan değerin de kabul edilmemesi gerekiyorsa bunu uygun pattern veya iş kontrolüyle ayrıca tanımlayın.

OpenAPI 3.0’da nullable string parçası {"type":"string","nullable":true}, OpenAPI 3.1’de {"type":["string","null"]} olarak ifade edilir. Sürümü değiştirirken yalnızca openapi satırını değiştirmek yerine ilgili şemaları da inceleyin.

İç içe nesne ve listeler

Bir sipariş birden çok satır içeriyorsa lines alanı array, her satır ise bir object olabilir. Aşağıdaki parça, ortak schema’ların nasıl birleştirildiğini gösterir; mevcut components.schemas tanımlarınıza ekleyin:

{
  "OrderLine": {
    "type": "object",
    "required": ["productCode", "quantity"],
    "additionalProperties": false,
    "properties": {
      "productCode": {"type": "string", "minLength": 1},
      "quantity": {"type": "integer", "minimum": 1}
    }
  },
  "OrderLines": {
    "type": "array",
    "minItems": 1,
    "maxItems": 50,
    "items": {"$ref": "#/components/schemas/OrderLine"}
  }
}

Burada minItems: 1 boş listeyi, satır içindeki required ise eksik ürün veya miktarı engeller. Nesnenin zorunlu alanları kendi seviyesinde tanımlanır; üst nesnenin required listesi alt nesnenin alanlarını kendiliğinden zorunlu yapmaz.

uniqueItems, bütün liste öğelerinin aynı olup olmadığını kontrol eder. “Aynı productCode iki farklı miktarla tekrarlanmasın” gibi bir iş anahtarı kuralı için ayrıca iş kontrolü gerekir.

Referansları kullanın

Ortak schema’lar components.schemas altında durur. Bir media type veya başka bir schema içinden yerel referans verilir:

{"$ref":"#/components/schemas/OrderRequest"}

Bu sayede aynı modelin her kopyasını ayrı düzenlemek yerine ortak tanımı değiştirirsiniz. Bir modeli yeniden adlandırdıktan veya silmeden önce kullanım yerlerini kontrol edin. Referanslanan model veya alanın silme düğmesi kapalıdır; details içindeki kullanım konumlarını inceleyip önce referansları değiştirin. Çözümlenemeyen referanslar tanılamada görünür.

Ortak model değişirse ne olur?

Örneğin OrderRequest iki operation’ın girdisiyse, quantity maximum değerini 100 yerine 20 yapmak her ikisinin kabul ettiği istekleri daraltır. Değişiklik önce taslağa, Save ile dosyaya, Reload veya Build ile ilgili çalışan sürüme geçer. Bir operation’ın response örneğini değiştirmek ise ortak schema’nın kuralını değiştirmez.

Değiştirmeden önce kullanım yerlerini inceleyin; doğru ve yanlış girdileri kullanan bütün operation’larda deneyin. İstemcilerinizin etkilenmesini değerlendirirken yeni zorunlu alanı, tür değişimini, daralan enum/sınırı ve kaldırılan response alanını özellikle kontrol edin.

Çalışan API harici URL veya başka dosyadan $ref yüklemez. Dışarıdan aldığınız sözleşmelerde gerekli tanımları components altına toplayın. Bir örneğin içindeki sıradan $ref metni ile gerçek schema referansı farklıdır; örnek veriyi iş modeliniz gerektirmiyorsa değiştirmeyin.

Örnek, varsayılan değer ve veri dönüşümü

Example, belgenin ve Mock denemesinin anlaşılmasını sağlar. Use generated example, schema’dan oluşturulan örneği Content example alanına kopyalar. Gerçekçi bir test için müşteri kodu, miktar ve diğer alanları sizin senaryonuza göre düzenleyin.

Default, sözleşmede varsayılanı anlatır; iş route’unun eksik girdiyi dolduracağını varsaymayın. Eksik değerin tamamlanması, alan adlarının değiştirilmesi, tarih biçiminin dönüştürülmesi ve JSON/XML eşlemesi akışta yapılır. Schema bir dönüşüm programı değildir.

format: password bir parola gücü kontrolü veya şifreleme ayarı değildir. readOnly ve writeOnly gibi yön bilgileri de route çıktısından alanları otomatik silmez. Dönecek veriyi route’ta açıkça oluşturun; hassas bir alanın response’a girmediğini gerçek çıktıda kontrol edin.

Üç ayrı kontrol katmanı

JSON isteklerde type, required, enum, sayısal sınırlar, string uzunluk/pattern, array ve object kuralları, yerel referanslar ve desteklenen birleşik tanımlar doğrulanır. allOf, anyOf, oneOf ve not gibi tanımları Source/Schema JSON ile yazabilirsiniz.

Bu birleşimler veriyi dönüştürmez veya iş akışında bir Choice dalı oluşturmaz. İç içe kullanırken önce örneklerin hangi şemaları geçtiğini kontrol edin. Temel bir object modeli yeterliyse, okunması zor bir birleşim yerine onu kullanın.

Request schema’sında recursive referanslar, boolean schema, özel schema dialect’leri ve $dynamicRef/unevaluatedProperties gibi desteklenmeyen ileri kurallar çalıştırma öncesi hata verir. Hata gösterilen tanımı sadeleştirin veya bu kuralı route’taki açık iş doğrulamasına taşıyın. Yalnızca yanıt modelinde bulunan ileri bir tanımın düzenlenebilir olması, runtime’da doğrulandığı anlamına gelmez.

JSON dışı gövdeler route’a metin olarak geçer. Yanıt schema doğrulaması otomatik etkin değildir. API güvenlik gereksinimleri de schema doğrulamasından ayrı olarak erişim politikasında uygulanır.

Kuralı gerçek istekle doğrulayın

Örnekteki OrderRequest için Try it → Running project üzerinden şu gövdeleri sırayla gönderin:

{"customerId":"C-100","quantity":2}

Bu girdi sözleşmeyi geçer; yanıtı iş route’u belirler.

{"customerId":"C-100","quantity":0}

İkinci girdi minimum kuralını ihlal eder. Beklenen sonuç bir istemci hata yanıtı ve Request contract checks alanında quantity ile ilgili açıklamadır. Geçersiz girdi iş route’una geçmemelidir.

Open schema setting görünüyorsa ilgili sınıra gidin. Kuralı değiştirdikten sonra Save → Reload yapıp aynı girdiyi yeniden gönderin. Mock ile alınan sonuç canlı doğrulamayı veya bağlı sistemin iş kurallarını kanıtlamaz.

Bu adımları tam sözleşme ve route ile denemek için sipariş API’si örneğini izleyin. Hata gövdesindeki location, rule ve message alanları hata teşhisinde açıklanır.