OpenAPI 3.1 Doğrulayıcı

Bu araç 3.1 dosyalarıyla ne yapar

Sürüm 3.1, şemaları JSON Schema 2020-12 ile hizalar. Bu doğrulayıcı şemaların içini hiç okumaz. Yalnızca üst düzeyi ve yol girdilerini inceler; dolayısıyla tür dizileri veya const gibi 3.1 şema özellikleri burada ne geçer ne de kalır. Sürüm değerinin kendisi de kontrol edilmez: her openapi alanı mevcut sayılır.

Dikkat edilmesi gereken iki 3.1 kalıbı

OpenAPI 3.1, bir belgenin yalnızca webhook’ları tanımlamasına ve paths alanını atlamasına izin verir. Bu araç paths alanını zorunlu tuttuğu için, spesifikasyon buna izin verse de böyle bir dosya hatayla bildirilir. Boş bir paths: {} nesnesi eklemek kontrolü geçirir.

Buradaki metot listesi get, post, put, patch, delete, head, options ile parameters, summary, description ve servers alanlarından oluşur. trace metodu spesifikasyonda vardır ama bu listede yer almaz; bu nedenle bilerek kullandıysanız göz ardı edebileceğiniz bir uyarı üretir. Uyarılar belgeyi geçersiz kılmaz.

Çalışılmış bir örnek

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Sonuç: bir hata, “Missing ‘paths’ object.” paths: {} ekleyin ve yapı kontrolü geçer.

Bunu ne zaman kullanmalı, ne zaman daha ileri gitmeli

Bir pull request açmadan veya bir iş ortağıyla paylaşmadan önce 3.1 dosyasının doğru biçimde olduğunu doğrulamak için bu sayfayı kullanın. Kontroller hızlıdır ve mesajlar açıktır. Yapı doğru olduğunda 3.1 şema kuralları yine de tam bir linter gerektirir, çünkü gerçek hataların çoğu oradadır: geçersiz tür tanımları, bozuk referanslar ve eksik yanıt tanımları. İki adımı alternatif değil, birbirini tamamlayan adımlar olarak görün.

trace gibi bilerek bıraktığınız bir uyarı varsa, incelemecilerin merak etmemesi için pull request’inize not düşün. Uyarılar geçerli sonucu asla değiştirmez, bu yüzden bırakılmaları güvenlidir. Paylaşmadan önce çözülmesi gereken öğeler hatalardır.