Bozuk bir Swagger dosyası nadiren kendini belli eder. YAML sorunsuz ayrıştırılır. Belgeler sayfası işlenir. Ardından bir ön uç geliştiricisi, spesifikasyonunuzdan bir istemci oluşturur, derleme eksik bir required alanında başarısız olur ve "bitmiş" API açıklamanızın üç commit önce bir $ref içinde yazım hatası olduğunu fark edersiniz. Spesifikasyon başından beri yanlıştı. Birisinin bir öğleden sonrasına mal olana kadar size hiçbir şey haber vermedi.
Bir Swagger doğrulayıcının yaptığı iş budur: OpenAPI veya Swagger dosyanızı okur ve henüz kimse kullanmadan önce belgenin gerçekten geçerli olup olmadığını size söyler. "Doğru görünüyor mu" değil, "OpenAPI Spesifikasyonuna uygun mu, her referansı çözümlüyor mu ve bir aracın güvenebileceği bir şemayı tanımlıyor mu?" sorularına cevap verir. Bir doğrulayıcı, sessiz yapısal hataları yüksek sesli, satır numaralı hatalara dönüştürür ve bu hataları saatlerce hata ayıklamak yerine saniyeler içinde düzeltirsiniz.
Bir Swagger doğrulayıcı aslında neyi kontrol eder?
Öncelikle isimlendirme. "Swagger" ve "OpenAPI", tarihin farklı noktalarında aynı şeyi tanımlar. Format, 2.0 sürümüne kadar Swagger olarak adlandırıldı, sonra OpenAPI Girişimi'ne bağışlandı ve yeniden adlandırıldı; 3.0, 3.1 ve 3.2'nin hepsi OpenAPI'dir. İnsanlar alışkanlık olarak hala "swagger doğrulayıcı" diyor ve çoğu araç hem Swagger 2.0'ı hem de OpenAPI 3.x'i kabul ediyor. Eğer sürüm geçmişi belirsizse, Swagger ile OpenAPI karşılaştırması bunu netleştirir. Son sürümler arasındaki farklar için, OpenAPI 3.2, 3.1 ve 3.0'da neler değişti makalesine bakınız.
Gerçek bir doğrulayıcı, sırasıyla üç iş yapar:
- Ayrıştırma. Dosya geçerli bir YAML veya JSON mu? Fazla bir sekme, yinelenen bir anahtar, kapatılmamış bir parantez, belgeyi asla yüklemez. Yakalanması en ucuz ve yayınlaması en utanç verici hata budur.
- Yapıyı Doğrulama. Belge OpenAPI şemasına uygun mu? Her işlem bir
responsesnesnesine ihtiyaç duyar. Her parametrenin birindeğerine ihtiyacı vardır. Bir$refvar olan bir şeyi işaret etmelidir. Çoğu gerçek hata burada gizlidir. - Referansları Çözümleme. OpenAPI belgeleri, yeniden kullanılabilir şemaları bir araya getiren
$refişaretçileriyle doludur. Bir doğrulayıcı her birini takip eder ve bir hedef eksikse, spesifikasyonun yasakladığı şekilde döngüselse veya yanlış dosyayı işaret ediyorsa başarısız olur.
Bu üçünü de geçerseniz, herhangi bir uyumlu aracın, kod üretecinin, sahte sunucunun, belge işleyicinin sorunsuz okuyabileceği bir belgeye sahip olursunuz. Herhangi birinden kalırsanız, hata terminalinizden daha az uygun bir yerde ortaya çıkar.
Sonradan sorun yaratan yakaladığı hatalar
Doğrulama, onsuz neyin gözden kaçtığını görene kadar soyut gelir. Bunlar, düzenleyicide zararsız görünen ancak akışın aşağısında gerçek olaylara dönüşen spesifikasyon hatalarıdır.
Bozuk $ref işaretçileri. Bir şemayı User'dan UserProfile'a yeniden adlandırırsınız ancak yanıt gövdesinin derinliklerinde bir referansı atlarsınız. YAML hala ayrıştırılır. Belgeler sayfanın geri kalanını hala işler. Kod üreteci sarkan işaretçiye çarpar ve eksik bir türle bir istemci yayınlar veya sadece çöker. Bir doğrulayıcı, kaydettiğiniz anda bozuk $ref'i işaretler.
Şema ve örnek uyumsuzluğu. Şemanız age'in bir tam sayı olduğunu söyler; örneğiniz "age": "thirty" gösterir. Swagger UI ikisini de memnuniyetle görüntüler. Spesifikasyondan oluşturulan bir sahte sunucu daha sonra tüketicilerin bir sayı beklediği yerde bir dize döndürür ve üç ekip ötedeki bir sözleşme testi, kimsenin dosyanıza kadar izleyemediği nedenlerden dolayı kırmızıya döner.
Eksik zorunlu parçalar. responses'ı olmayan bir işlem. URL şablonunda bildirilen ancak parameters içinde asla tanımlanmayan bir yol parametresi. content'i olmayan bir requestBody. Her biri teknik olarak hatalı biçimlendirilmiş bir belgedir ve her biri, spesifikasyonu ilk hangi aracın okuduğuna bağlı olarak farklı bir aşağı akış semptomu üretir.
Tip ve format kayması. Arka ucunuzun bir Unix zaman damgası olarak döndürdüğü bir alanda format: date-time. Aslında bir dizi olan bir şey üzerinde type: string. Bunlar yapısal doğrulamayı geçer ancak spesifikasyon ile çalışan API arasındaki sözleşmeyi bozar, bu da ele alacağımız ayrı bir sorundur.
Desen tutarlıdır: bir spesifikasyon hatası, siz onu yaparken görünmezdir ve başka biri onu tükettiğinde pahalıdır. Doğrulama, maliyeti ucuz olduğu yere geri taşır.
Bir Swagger dosyası elle nasıl doğrulanır?
Başlamak için bir platforma ihtiyacınız yok. Bugün bir spesifikasyonu doğrulamak için üç hızlı yol vardır.
Swagger Düzenleyici. YAML dosyanızı Swagger Düzenleyici'ye yapıştırın; siz yazdıkça doğrular ve sağ kenar boşluğunda satır numaralarıyla hataların altını çizer. Tek bir dosyayı hızlıca kontrol etmenin en hızlı yolu budur ve ücretsizdir. Sınırlaması, tek bir metin kutusu olmasıdır: belgeyi doğrular ancak gerçek API'nizin hala ona uygun olup olmadığı hakkında hiçbir şey yapmaz ve görsel bir şema oluşturucu olmadan elle YAML yazarsınız. Formatı öğrenmek için bu iyidir. Bir ekibin güvendiği bir spesifikasyon için, birkaç sekmeye ihtiyaç duyan bir iş akışında sadece bir sekmedir.
Spectral gibi bir linter. Stoplight'ın Spectral'i, ham geçerliliğin ötesine geçerek stil kurallarına odaklanan açık kaynaklı bir CLI'dır. Yapısal geçerliliği kontrol eder ve bir kural kümesi uygulamanıza olanak tanır: her işlem bir açıklamaya ihtiyaç duyar, her şema özelliği bir türe ihtiyaç duyar, adlandırma sizin kuralınıza uyar. Spectral, birçok dosya arasında spesifikasyon stilini yönetmek için gerçekten sınıfının en iyisi bir araçtır ve tutarlı API tasarımı sizin endişeniz ise, benimsemeye değerdir. Şöyle çalıştırırsınız:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Denge, kapsamdadır. Spectral belgeyi doğrular ve lint eder. Bir istek çalıştırıcısı değildir; spesifikasyonun tanımladığı API'nin gerçekten spesifikasyonun iddia ettiği gibi davranıp davranmadığını size söylemez. Bu farklı bir katmandır ve çoğu üretim sürprizinin yaşandığı katmandır.
Çevrimiçi bir doğrulayıcı uç noktası. Swagger projesi, barındırılan bir spesifikasyon URL'si için geçme veya kalma rozeti döndüren bir doğrulayıcı hizmeti yayınlar. Bir README rozeti için kullanışlıdır, ancak etkileşimli bir düzeltme döngüsü için o kadar değil. Bağımsız seçeneklerin daha derinlemesine kapsamı için, en iyi OpenAPI doğrulama araçlarının bir özetini ve OpenAPI spesifikasyonları nasıl doğrulanır konusunda odaklanmış bir kılavuzu tutuyoruz.
Üçü de belgeyi doğrular. Hiçbiri geçerli bir spesifikasyon ile doğru bir API arasındaki boşluğu kapatmaz. Bir sonraki bölüm bu boşluğun ne olduğunu açıklar.
Apidog nerede devreye giriyor: spesifikasyonu doğrulayın, sonra API'nin ona uygun olduğunu kanıtlayın
Apidog hepsi bir arada bir API platformudur: şemayı tasarlarsınız, isteklerin hatalarını ayıklarsınız, otomatik test senaryoları oluşturursunuz, uç noktaları taklit edersiniz ve belgeleri tek bir çalışma alanında yayınlarsınız. Spesifikasyon doğrulama, ek olarak kurduğunuz ayrı bir araç değildir; platformda çalışmanın bir özelliğidir.
Bir Swagger veya OpenAPI dosyasını içe aktardığınızda veya görsel düzenleyicide bir tane tasarladığınızda, Apidog onu içeri alırken ayrıştırır ve doğrular. Hatalı biçimlendirilmiş bir belge, bozuk bir $ref, tipi olmayan bir parametre gibi sorunlar, üç araç aşağı akışta değil, siz çalışırken ortaya çıkar. Düzenleyici görsel olduğu için, el yazısıyla yapılan YAML hatalarının tamamı asla meydana gelmez: alan zorunlu bir açılır menü olduğunda bir parametredeki in değerini unutamazsınız. Spesifikasyon yapısal olarak geçerlidir.
Bu, belgeyi ele alır. Daha zor sorun, bir şey söyleyen bir spesifikasyon ile başka bir şey yapan bir API arasındaki yavaş anlaşmazlık olan kaymadır. Bağımsız bir doğrulayıcı bunu yakalayamaz, çünkü dosya geçerlidir; yanlış olan çalışan hizmettir. Pek çok kayan Swagger belgeleri ve Postman koleksiyonlarının arkasındaki hata modu budur.
Apidog, spesifikasyonu testler için doğruluk kaynağı yaparak bu boşluğu kapatır. OpenAPI spesifikasyonunuzdan doğrudan test senaryoları oluşturursunuz, ardından gerçek yanıtların beyan ettiğiniz şemayla eşleştiğini iddia edersiniz. Spesifikasyon age'in bir tam sayı olduğunu söylediğinde ve API bir dize döndürdüğünde, test başarısız olur ve bu başarısızlık, elle bakımı yapılan bir kopyasına karşı değil, spesifikasyonun kendisine karşı gerçekleşir. Doğrulayıcı sorusu sürekli bir hale gelir: "Bu dosya kaydettiğimde geçerli miydi" değil, "canlı API şu anda sözleşmesine hala sadık mı?" Eğer iddia mekanizmalarını merak ediyorsanız, API iddiaları: pratik bir rehber yanıt şeklini, durumunu ve alanlarını doğrulamayı kapsar.
Doğrulamayı hatırlanmaktan ziyade otomatik olarak uygulanmasını isteyen ekipler için Apidog, tasarım döngüsünün bir parçası olarak API'lerin OpenAPI standartlarına uyumlu kalmasını da sağlar.
Apidog CLI ile CI'da spesifikasyon odaklı doğrulama çalıştırma
Yalnızca birisi düzenleyiciyi açtığında çalışan bir doğrulayıcı, sonunda atlanan bir doğrulayıcıdır. Çözüm, doğrulamayı, her gönderimde insan müdahalesi olmadan çalıştığı işlem hattına koymaktır. Apidog komut satırı çalıştırıcısı bunun içindir.
CLI, apidog-cli adlı bir npm paketidir. Apidog'da oluşturduğunuz test senaryolarını, Node.js yüklü herhangi bir ortamdan, başsız modda çalıştırır. Tek bir komutla yükleyin:
npm install -g apidog-cli
Ardından, canlı yanıtlarınızın spesifikasyonla eşleştiğini iddia eden aynı kaydedilmiş senaryoyu, bir ortama karşı çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Bu bayrakların ne işe yaradığına dair birkaç not. -t test senaryosu kimliğidir. -e ortam kimliğidir, böylece aynı kontrolleri bir çekme isteğinde hazırlık ortamına ve dağıtımdan sonra üretim ortamına yönlendirebilirsiniz. -r rapor formatlarını seçer: okunabilir derleme günlüğü çıktısı için cli ve bir CI panosunu beslemek için html, json veya junit ekleyebilirsiniz. --access-token bir CI gizlisinde yer almalı, asla satır içi olmamalıdır. Hem jetonu hem de hazır komutu, Apidog içindeki senaryonun CI/CD sekmesinden oluşturursunuz. Tam bayrak yüzeyi için apidog run --help komutunu çalıştırın veya tam Apidog CLI rehberini okuyun.
Bunu gerçek bir geçit yapan detay: bir iddia başarısız olduğunda CLI sıfır olmayan bir durum koduyla çıkar. CI sistemleri bu çıkış kodunu okur. Başarısız bir şema kontrolü adımı başarısız eder, bu da işi başarısız eder ve birleşmeyi engeller. Böylece, API'niz OpenAPI sözleşmesiyle eşleşmeyi bıraktığı anda, değişiklik yayınlanmadan önce derleme kırmızıya döner, bir tüketici bilet açtıktan sonra değil. Bir dosyayı bir kez doğrulamakla, her commit'te sözleşmeyi doğrulamak arasındaki fark budur. Aynı çıkış kodu davranışı, çalıştırıcının Newman olmadan CI'da Postman koleksiyonlarını çalıştırmak gibi herhangi bir CI platformuna uymasının nedenidir.
Ekibinizin API'yi zaten tasarladığı yerde spesifikasyon doğrulama ve sözleşme testi istiyorsanız Apidog'u indirin.
Pratik bir doğrulama iş akışı
Parçaları bir araya getirerek, sadece son aşamada değil, her aşamada spesifikasyon hatalarını yakalayan bir dizi aşağıdadır:
- Doğrulayan bir düzenleyicide tasarlayın veya içe aktarın. Mevcut bir Swagger dosyasını içe aktarın veya Apidog'un görsel tasarımcısında oluşturun, belge içeri alınırken ayrıştırılır ve yapısal olarak doğrulanır. Bozuk referanslar ve eksik tipler hemen ortaya çıkar.
- Bir kural kümeniz varsa stil için lint edin. Kuruluşunuz adlandırma ve açıklama kurallarını uyguluyorsa, hızlı bir ön-commit kontrolü olarak Spectral'i çalıştırın. Geçerlilik ve şirket içi stil farklı endişelerdir; ikisini de kapsayın.
- Spesifikasyondan testler oluşturun. OpenAPI belgesini test senaryolarına dönüştürün, böylece iddialarınız, kayan ayrı bir kopyaya değil, yayınladığınız aynı tanıma bağlı olur.
- Her push'ı CLI ile kontrol edin.
apidog runkomutunu işlem hattınıza bağlayın, böylece spesifikasyon-gerçeklik uyuşmazlığı derlemeyi otomatik olarak başarısız kılar. - Spesifikasyonu doğruluk kaynağı olarak kabul edin. Tasarım değiştiğinde, testler aynı dosyayı işaret eder, bu nedenle elle senkronize edilecek hiçbir şey kalmaz.
1. ve 2. adımlar belgeyi doğrular. 3'ten 5'e kadar olan adımlar sözleşmeyi doğrular. İkisine de ihtiyacınız vardır ve tüm bunları yapmanın en ucuz yolu dört tarayıcı sekmesi yerine tek bir çalışma alanıdır.
Kısa versiyon
Bir swagger doğrulayıcı, yazarken görünmeyen ve başkası okuduğunda pahalıya mal olan yapısal hataları, bozuk referansları, eksik tipleri, hatalı biçimlendirilmiş YAML'yi yakalar. Belgeyi doğrulamak, tavan değil, tabandır. Gerçekten üretime ulaşan hatalar, geçerli bir spesifikasyonun değişen bir API ile sessizce eşleşmemeye başladığı durumlardır ve dosya düzeyindeki hiçbir doğrulayıcı bunları göremez.
Çözüm, iki katmanda doğrulama yapmak ve her ikisini de tek bir yere koymaktır: belgeyi tasarlarken doğrulayın, ardından her gönderimde gerçek yanıtları spesifikasyona göre iddia ederek sözleşmeyi doğrulayın. Apidog, birincisini yapısal olarak, ikincisini ise apidog-cli çalıştırıcısının CI'da kontrol ettiği senaryolar aracılığıyla yapar. Spesifikasyon doğruluk kaynağı olarak kalır, gerçeklik ondan saptığı anda derleme kırmızıya döner ve bozuk bir Swagger dosyası, bir öğleden sonra çok geç keşfettiğiniz bir şey olmaktan çıkar.