OpenAPI JSON Doğrulayıcı

Başarısız kontrolün ardındaki yaygın JSON hataları

JSON, YAML’dan daha katıdır; bu nedenle elle düzenlenmiş bir dosyadaki başarısızlıkların çoğu API tasarımından değil sözdiziminden kaynaklanır. Yaygın nedenler: son özellikten sonra bir virgül, çift tırnak yerine tek tırnak, bir yorum (JSON yorumlara izin vermez) veya uzun bir paths nesnesinden sonra eksik bir kapanış süslü parantezi. Bozuk bir dosya genellikle “Could not parse as JSON or YAML” mesajıyla biter ya da hiçbir kullanılabilir veri okunamadığı için eksik alan hataları verir.

Yalnızca bir ayrıştırma hatası görüyorsanız önce sözdizimi hatasını bulun. Yapısal kontroller, belge bir nesne olarak okunduktan sonra çalışır.

Çalışılmış bir örnek

Bu küçük belgeyi alın:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Ayrıştırılır, openapi alanı ve paths nesnesi mevcuttur. Yine de rapor şunu gösterir:

Tek bir hata olduğu için belge geçerli sayılmaz. info içine "version": "1.0.0" ekleyin ve anahtarı /orders olarak yeniden adlandırın. İkinci bir çalıştırma her iki bulguyu da temizler.

Geçmenin neyi ifade ettiği ve neyi ifade etmediği

Temiz bir rapor, iskeletin doğru olduğu anlamına gelir. $ref bağlantılarını takip etmez, şemaları kontrol etmez ve her işlemin yanıtları olup olmadığını doğrulamaz. Dosyayı depoya eklemeden önce hızlı bir kapı olarak görün, ardından daha derin kurallar için tam bir linter çalıştırın.

JSON belirtimleri için pratik bir iş akışı

Belirtimi sürüm kontrolünde tutun ve paths alanına dokunan her commit’ten önce buraya yapıştırın. Kontrol hızlı olduğu için, birkaç kişinin değişikliklerini birleştirdikten sonra, yinelenen anahtarların ya da yanlış yere konmuş bir parantezin en olası olduğu anlarda bir akıl sağlığı adımı işlevi görür. JSON’unuz bir derleme betiğiyle üretiliyorsa şablonu değil üretilen çıktıyı yapıştırın; böylece okuyucuların gerçekte alacağı şeyi test edersiniz. Rapor temiz olduğunda dosyayı paylaşabilir ya da bir belge üreticisine verebilirsiniz, çünkü üst düzey yapının sağlam olduğundan daha fazla emin olursunuz.