Bir OpenAPI belirtimi bir sözleşmedir. Kod üreteçleri onu okur, belgeler ondan oluşturulur, sahte sunucular onun üzerinde çalışır ve istemci SDK'leri ondan üretilir. Belirtim yanlış olduğunda, bu alt akış artefaktlarının her biri hatayı miras alır. Bir doğrulayıcı, sorun yayılmadan önce belirtim dosyasındaki sorunu yakalar.
Bu derleme, kullanmaya değer OpenAPI doğrulayıcı araçlarını, her birinin ne işe yaradığını ve gerçek bir iş akışına nasıl uyduklarını kapsar. Bazıları ham sözdizimini kontrol eder. Diğerleri stil ve tasarım kurallarını uygular. En iyi kurulum genellikle her ikisini birleştirir ve bu kılavuz onu nasıl bir araya getireceğinizi açıklar.
Belirtimi doğrulamanın önemi
Bir doğrulayıcının çözdüğü iki farklı sorun vardır ve bunları karıştırmak kafa karışıklığına neden olur.
Birincisi doğruluktur. Dosya überhaupt geçerli bir OpenAPI mi? Yanlış girintili bir YAML bloğu, hiçbir yere işaret etmeyen bir $ref, gerekli description'ı eksik olan bir yanıt, bir tür adında yazım hatası olan bir şema. Bunlar nesnel hatalardır. Dosya ya OpenAPI şemasına göre ayrıştırılır ya da ayrıştırılmaz. Bir doğruluk doğrulayıcısı size evet veya hayır cevabı verir.
İkincisi kalitedir. Belirtim geçerli, ama iyi mi? Her işlem bir özete sahip olmalı. Yol adları tutarlı olmalı. Her hata yanıtı belgelenmeli. Güvenlik bildirilmelidir. Bunların hiçbiri OpenAPI şeması tarafından gerekli değildir, ancak bunları atlamak, tüketimi zahmetli olan teknik olarak geçerli bir belirtim üretir. Bir linter bu tasarım kurallarını uygular. Her iki tür sorunu da erken yakalamak, bir SDK gönderildikten sonra yakalamaktan çok daha ucuzdur; bu, daha geniş anlamda API sözleşme testinin arkasındaki mantıkla aynıdır.
Bilmeye değer doğrulayıcı araçları
Swagger Editor
Swagger Editor, OpenAPI projesinin resmi tarayıcı tabanlı düzenleyicisidir. Belirtiminizi sol tarafa yapıştırır veya yazarsınız ve doğrulama hatalarını ve işlenmiş bir önizlemeyi sağda, canlı olarak görürsünüz. Sıfır kurulumla bir belirtimin sözdizimsel olarak geçerli olup olmadığını kontrol etmenin en hızlı yoludur. Düzenleme ve hızlı kontroller için mükemmeldir, otomatikleştirilmiş pipeline çalıştırmaları için daha az uygundur. Swagger Editor ücretsizdir ve tamamen tarayıcıda çalışır.
Spectral
Stoplight'tan Spectral, çoğu ekibin kalite kontrolü için tercih ettiği linter'dır. OpenAPI ve AsyncAPI için kural kümeleri sunar ve asıl değeri özel kurallardır. Her işlemin bir açıklamaya sahip olmasını zorunlu kılmak veya yollardaki sondaki eğik çizgileri yasaklamak gibi kendi kurallarınızı uygulamak için YAML veya JavaScript'te kurallar yazarsınız. Komut satırından çalışır, bu da onu CI için doğal bir uyum sağlar. Spectral projesi açık kaynaklıdır.
openapi-spec-validator
openapi-spec-validator, tek bir işi iyi yapan odaklanmış bir Python aracıdır: bir belirtimi, 2.0, 3.0 ve 3.1 sürümleri için resmi OpenAPI şemasına göre kontrol eder. Stille ilgili bir görüşü yoktur. Dosyanın yapısal olarak doğru olup olmadığını söyler. Bir kütüphane veya CLI olarak, Python tabanlı derleme adımlarına ve pre-commit hook'larına temiz bir şekilde entegre olur. Kesin bir geçiş veya hata doğruluk geçidi istediğinizde, bu temiz bir seçimdir.
Apidog
Apidog, entegre bir tasarım iş akışının parçası olarak belirtimi doğrular. Bir OpenAPI tanımı oluşturduğunuzda veya içe aktardığınızda, düzenleyicide yapısal sorunları işaretler. Daha ayırt edici özelliği, çalışma zamanı doğrulamasıdır: canlı API yanıtlarını belirtiminizde belirtilen şemaya göre kontrol eder, böylece uygulamanın sözleşmeyle eşleşmediği sapmaları yakalarsınız. Bu, geçerli bir belge ile doğru bir API arasındaki boşluğu kapatır. Belirtimleri tek bir araçta tasarlamak ve doğrulamak için Apidog'u indirin.
Redocly CLI
Redocly CLI, linting, doğrulama ve belge oluşturmayı bir araya getirir. OpenAPI şemasına karşı doğrulama yapar, yapılandırılabilir bir kural kümesi sunar ve çok dosyalı belirtimleri tek bir pakete dönüştürebilir. Redoc ile belge oluşturan ekipler, başka bir bağımlılık eklemeden aynı araç zincirinde doğrulama yapabilirler.
Vacuum
Vacuum, Go ile yazılmış hızlı bir OpenAPI linter'ıdır. Satış noktası, bazı JavaScript tabanlı linter'ların yavaşladığı çok büyük belirtimlerdeki hızıdır. Spectral tarzı kurallarla uyumludur, bu nedenle bir ekip az bir yeniden çalışma ile geçiş yapabilir. Yaygın bir API yüzeyine sahip bir monorepo için performans farkı dikkat çekicidir.
Karşılaştırma tablosu
| Araç | Tür | Kontrol Ettiği | CI'da Çalışır | En İyisi İçin |
|---|---|---|---|---|
| Swagger Editor | Tarayıcı düzenleyici | Sözdizimi, şema | Hayır | Canlı düzenleme ve hızlı kontroller |
| Spectral | CLI linter | Stil, özel kurallar | Evet | Tasarım kurallarını uygulama |
| openapi-spec-validator | CLI / Python kütüphanesi | Şema doğruluğu | Evet | Kesin geçiş veya hata kapısı |
| Apidog | Entegre platform | Şema + çalışma zamanı sapması | Evet | Tasarım artı yanıt doğrulama |
| Redocly CLI | CLI | Şema, stil, paketleme | Evet | Belgeler ve doğrulama bir arada |
| Vacuum | CLI linter | Stil, Spectral kuralları | Evet | Çok büyük belirtimler, hız |
Bir doğrulama iş akışı nasıl oluşturulur
Tek bir araç seçmezsiniz. Onları katmanlarsınız.
Düzenlediğiniz yerden başlayın. Bir belirtim yazarken, yazarken hataların ortaya çıkması için Swagger Editor'ı veya entegre bir platformu kullanın. Bu, açık hataları hemen yakalar ve bunları daha sonra yakalamaktan çok daha ucuzdur.
CI'da bir doğruluk kapısı ekleyin. Belirtimi etkileyen her çekme isteğinde openapi-spec-validator'ı veya eşdeğer bir CLI'ı çalıştırın. Dosya OpenAPI şemasına göre doğrulanmazsa, derleme başarısız olur. Bu pazarlık konusu değildir ve ikilidir.
Yanına bir kalite kapısı ekleyin. Ekibinizin üzerinde anlaştığı bir kural kümesiyle Spectral'i veya büyük belirtimlerde Vacuum'u çalıştırın. Yerleşik OpenAPI kurallarıyla başlayın, ardından kendi kurallarınız için özel kurallar ekleyin. Kural kümesini sürüm kontrolünde tutun, böylece API ile birlikte gelişir. Bu, CI/CD'de testleri otomatikleştirmeyi güvenilir kılan disiplinle aynıdır: kontrol, birisi hatırladığında değil, her zaman çalışır.
Son olarak, çalışan API'yi belirtime göre doğrulayın. Uygulama ondan uzaklaşmış olsa bile bir belirtim mükemmel olabilir. Apidog aracılığıyla veya test paketinizdeki sözleşme testleri aracılığıyla çalışma zamanı doğrulaması, API'nin hala sözleşmesiyle eşleştiğini doğrular. Test tarafı için, faydalı API iddiaları yazmak, yanıtların belgelenmiş şemaya göre nasıl kontrol edileceğini kapsar.
Yaygın bir hata: bir kez doğrulama
Birçok ekip, bir belirtimi ilk yazdıklarında bir kez doğrular, sonra bir daha asla doğrulamaz. Belirtim o noktadan itibaren çürür. Bir geliştirici koda bir uç nokta ekler ve belirtimi unutur. Biri bir yanıt şeklini değiştirir. Altı ay sonra, belirtim artık var olmayan bir API'yi tanımlar ve üretilen SDK'ler ve belgeler sessizce yanlış olur.
Doğrulama sürekli olmalıdır. Belirtimde yapılan her değişikliğin kontrol edilmesi ve API'de yapılan her değişikliğin belirtime göre kontrol edilmesi için CI'a bağlayın. Bir belirtim hatasını, başarısız bir birim testini ele aldığınız gibi ele alın: derleme geçmez. Prensip, genel olarak otomatik testin arkasındakiyle aynıdır; yani bir kontrol, kimse çalıştırmaya karar vermeden çalışırsa değerlidir.
Doğru OpenAPI sürümüne göre doğrulama yapmak da yardımcı olur. 3.1 sürümü, OpenAPI'yi JSON Şema ile uyumlu hale geldi ve bu, bazı şema yapılarının davranışını değiştirdi. Araçlarınız 3.0'ı varsayıyor ancak belirtiminiz 3.1'i beyan ediyorsa, yanıltıcı sonuçlar alabilirsiniz. Resmi OpenAPI Belirtimi, sürüm farklılıklarını belgeler ve çoğu doğrulayıcı, sürümü açıkça sabitlemenize izin verir.
Doğrulayıcıların sizin kaçıracağınız neleri yakaladığı
Doğrulamanın ortaya çıkardığı sorun türleri hakkında somut olmak faydalıdır, çünkü "belirtim yanlış" ifadesi harekete geçmek için çok belirsizdir.
Yapısal hataları hayal etmek en kolay olanıdır. Var olmayan bir şemayı işaret eden bir $ref. OpenAPI'nin gerektirdiği bir description'a sahip olmayan bir yanıt nesnesi. URL şablonunda bildirilen ancak parametreler listesinde hiç tanımlanmamış bir yol parametresi. Örnek bir dize gösterirken type: integer diyen bir şema. Bir doğruluk doğrulayıcısı bunların her birini işaretler ve her biri aksi takdirde bir kod üreteciyi bozabilir veya bozuk bir SDK üretebilir.
Kalite sorunları daha inceliklidir ve daha yaygındır. operationId'si olmayan bir işlem, üretilen istemci yöntemi adlarını çirkin veya kararsız hale getirir. Bazı rotaların snake_case kullandığı ve diğerlerinin camelCase kullandığı tutarsız yol büyük/küçük harf kullanımı. 200 yanıtını belgeleyen ancak 400 veya 401'i asla belgelemeyen uç noktalar, böylece tüketicilerin hataların nasıl göründüğüne dair hiçbir fikri olmaz. API aslında gerektirirken isteğe bağlı olarak işaretlenmiş bir istek gövdesi. Bunların hiçbiri bir ayrıştırıcıyı bozmaz, ancak hepsi API'yi kullanmayı zorlaştırır ve bu sınırı koruyan bir linter'dır. Gerçek davranışa bağlantı, belirtim temizlendikten sonra API sözleşme testinin doğruladığı şeydir.
Doğrulamayı tasarıma öncelik veren bir iş akışına dahil etme
Birçok ekip artık kodu yazmadan önce API'yi tasarlıyor, önce OpenAPI belirtimini üretiyor ve ondan sunucu taslakları, sahteleri ve belgeler oluşturuyor. Bu modelde doğrulama daha da önemlidir, çünkü belirtim mevcut bir API'nin belgelemesi değildir; her şeyin üzerine inşa edildiği doğruluk kaynağıdır. Belirtimdeki bir kusur, üretilen sunucuda bir kusur haline gelir.
Tasarım öncelikli bir akışta, tasarım anında doğrulama yapın. Düzenleyici düzeyindeki kontroller, belirtim şekillenirken, herhangi bir kod oluşturma çalıştırılmadan önce hataları yakalar. Daha sonra CI geçitleri, hiçbir şeyin gerilemediğini doğrular. Belirtim aynı zamanda sahte sunucuyu da yönlendirdiğinden, temiz bir belirtim, sahtenin doğru davrandığı anlamına gelir, bu da ön uç ve istemci ekiplerinin güvenilir bir yer tutucuya karşı geliştirme yapmasını sağlar. Bir belirtimin sahteyi nasıl beslediğini görmek isterseniz, test için bir API'yi taklit etme hakkındaki kılavuzumuz bağlantıyı gösterir. Bu disiplin kendini amorti eder: belirtimi geçerli tutmak için harcanan her saat, daha sonra uyumsuz istemcilerde hata ayıklamak için harcanan birkaç saati kurtarır.
Sıkça sorulan sorular
Bir OpenAPI doğrulayıcı ile bir linter arasındaki fark nedir?
Bir doğrulayıcı, belirtimin OpenAPI şemasına göre yapısal olarak doğru olup olmadığını kontrol eder ve geçiş veya hata cevabı verir. Bir linter, her işlemin bir açıklamaya sahip olup olmadığı veya yol adlandırmasının tutarlı olup olmadığı gibi kalite ve stili kontrol eder. Birçok araç her ikisini de yapar, ancak farklı sorulara cevap verirler ve güçlü bir iş akışı her ikisini de kullanır.
Bir OpenAPI belirtimini ücretsiz olarak doğrulayabilir miyim?
Evet. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI ve Vacuum hepsi ücretsiz ve açık kaynaklıdır. Apidog, ücretsiz katmanında belirtimleri doğrular ve çalışma zamanı kontrolleri ekler. Maliyet gerekçesiyle doğrulamayı atlamak için bir neden yoktur.
OpenAPI 3.0 ve 3.1'i farklı şekilde mi doğrulamalıyım?
Onları aynı araçlarla doğrulamanız gerekir, ancak sürümü sabitleyin. OpenAPI 3.1, JSON Şema ile uyumlu hale geldi ve bazı şema davranışlarını değiştirdi, bu nedenle 3.0 bekleyen bir doğrulayıcı, 3.1 belirtiminde yanlış hatalar bildirebilir. Araçlarınızın belirtiminizin beyan ettiği sürümü desteklediğinden emin olun.
Belirtim doğrulaması nerede çalışmalı?
İki yerde. Belirtimi yazarken düzenleyicinizde canlı olarak, böylece hatalar hemen ortaya çıkar ve her çekme isteğinde CI'da, böylece hiçbir şey bozuk veya düşük kaliteli bir belirtimle birleşmez. Yalnızca düzenleyici doğrulamayı atlamak kolaydır; CI doğrulaması değildir.
API'mın belirtimine uygun olduğunu nasıl kontrol ederim?
Belirtim doğrulaması yalnızca belgenin doğru olduğunu onaylar, uygulamanın ona uygun olduğunu değil. Sapmayı yakalamak için, canlı API yanıtlarını belirtimdeki şemaya karşı karşılaştıran sözleşme testleri veya çalışma zamanı doğrulaması çalıştırın. Apidog bunu doğrudan yapar ve sözleşme test çerçeveleri bunu bir test paketinde yapar.