Dredd Kullanmadan API'nizi Spesifikasyonuna Göre Nasıl Doğrulayabilirsiniz

Dredd gerçek bir sorunu temiz bir şekilde çözer. Onu bir API açıklamasına, bir OpenAPI belgesine veya bir API Blueprint dosyasına ve çalışan bir sunucuya yönlendirirsiniz. Açıklamadaki her örneği okur, eşleşen isteği canlı arka uca gönderir ve gerçek yanıtın spesifikasyonun vaat ettikleriyle eşleşip eşleşmediğini kontrol eder. Eğer spesifikasyonunuz GET /orders/{id} isteğinin id ve status alanlarıyla birlikte 200 döndürdüğünü söylüyorsa, Dredd çalışan servisin gerçekten de bunu yaptığını onaylar. Spesifikasyon, sessizce çürüyen bir belge olmaktan çıkar ve yüksek sesle başarısız olan bir teste dönüşür.

Uygulamayı API açıklamasına göre doğrulama fikri doğru bir fikirdir. Bir spesifikasyonun söyledikleri ile bir servisin yaptıkları arasındaki sapma, API çalışmalarındaki en pahalı sessiz hatalardan biridir. Bir ön uç ekibi belgelenmiş sözleşmeye göre kod yazar, arka uç bir alanın adını değiştirir, kimse belgeyi güncellemez ve hata üretimde ortaya çıkar. Dredd tam olarak bu tür arızaları yakalar ve yıllardır bunu komut satırından yapmak için başvurulan açık kaynaklı bir araç olmuştur.

Sürtünme konseptte değil, kurulum ve sürdürmededir. Dredd, kendi yapılandırma dosyasına, önemsiz durumların ötesindeki her şey için seçtiğiniz dilde bir kanca dosyasına ve diğer her şeyin yanı sıra elle sürdürdüğünüz ayrı bir spesifikasyon artefaktına ihtiyaç duyan bir Node.js CLI'sidir. Eğer Dredd'in size verdiği aynı sonucu, yani uygulamanızın OpenAPI sözleşmesiyle eşleşmemesi durumunda başarısız olan bir CI geçidini, bir kanca araç zinciri kurmadan ve spesifikasyonu üçüncü, ayrı bir dosya olarak tutmadan istiyorsanız, Apidog bu iş akışı için tasarlanmıştır. Spesifikasyonu, testleri ve doğrulamayı tek bir projede tutar ve tümünü bir npm CLI'dan başsız bir şekilde çalıştırır. Bu kılavuz, Dredd'in neyi iyi yaptığını adil bir şekilde belirtir ve entegre yolun nerede kazandığını açıkça ortaya koyar.

Dredd Neleri İyi Yapar

Önce Dredd'in hakkını verelim, çünkü bu ünü hak etti.

Uygulamayı test eder, sahte bir nesneyi değil. İşin özü budur. Birçok araç OpenAPI dosyanızın iyi biçimlendirilmiş olduğunu veya sahte bir sunucunun davrandığını doğrular. Dredd daha zor bir şey yapar: gerçek çalışan arka uca isabet eder ve geri gelen gerçek baytları belgelenmiş örneklere göre kontrol eder. Başarılı bir Dredd çalıştırması, dağıttığınız hizmetiniz ve spesifikasyonunuzun şu anda, teoride değil, hemfikir olduğu anlamına gelir.

Hem API Blueprint hem de OpenAPI dillerini konuşur. Dredd, markdown tabanlı açıklama formatı olan API Blueprint ile birlikte büyüdü ve daha sonra OpenAPI 2 ve 3 desteğini ekledi. Eski bir Blueprint dosyanız veya bir Swagger belgeniz varsa, Dredd bunu dönüştürme adımı olmadan okuyabilir.

Dilden bağımsız kancalar. Varsayılan istek-karşılaştırma döngüsü yeterli olmadığında, kimlik doğrulama belirteçlerine ihtiyacınız olduğunda, bir testten önce bir veritabanını doldurmanız gerektiğinde, bir işlemi atlamanız gerektiğinde, Dredd kancalar yazmanıza izin verir. Kanca işleyicisi varsayılan olarak Node'da çalışır, ancak Dredd Python, Ruby, Go, PHP, Rust ve daha fazlasında kancalar için protokol desteği sunar. Ekibiniz kurulum mantığını zaten bildiği bir dilde yazar.

Açık kaynaklı ve CI uyumludur. Dredd, npm install -g dredd komutuyla kurulur, tek bir komut olarak çalışır ve bir doğrulama başarısız olduğunda sıfırdan farklı bir çıkış koduyla sonlanır, bu sayede herhangi bir CI sistemi bir derlemeyi buna bağlayabilir. SaaS hesabı, koltuk fiyatlandırması, imzalanacak hiçbir şey yoktur. Kendi kendine barındırılan, komut dosyasıyla çalıştırılabilen bir sözleşme kontrolü isteyen bir ekip için bu önemlidir.

Bunların hiçbiri doldurma değildir. Dredd, açık bir görevi olan sağlam bir araçtır. Asıl soru, onun modeli olan üç ayrı artefakt ve bir kanca dosyasının, sizin gerçekten nasıl çalışmak istediğinizle eşleşip eşleşmediğidir.

Sürtünmenin Olduğu Yerler

Dredd modeliyle birlikte üç maliyet gelir ve bunların ne kadar zarar verdiği kurulumunuza bağlıdır.

Spesifikasyon, elle sürdürdüğünüz üçüncü bir artefakttır. Dredd, uygulamayı bir açıklama dosyasına göre doğrular ki bu tamamen doğrudur, ancak bu açıklama genellikle API'yi tasarladığınız ve test ettiğiniz yerden ayrı durur. Bir openapi.yaml dosyasını elle düzenlersiniz, test senaryolarınızı başka bir yerde tutarsınız ve çalışan servisi yine başka bir yerde tutarsınız. Dredd bu üçünden ikisini birbirine karşı kontrol eder. Spesifikasyonun kendisini doğru tutmak hala manuel bir iştir ve gerçeklikten sessizce uzaklaşmış bir spesifikasyon, yeşil görünen ama yanlış bir Dredd çalıştırması üretir.

Kancalar yazdığınız ve sürdürdüğünüz kodlardır. API'nizin kimlik doğrulama, sıralama veya test verilerine ihtiyaç duyduğu anda, örnek odaklı döngü yeterli olmaktan çıkar. Bir hooks.js (veya Python ya da Ruby eşdeğeri) yazarsınız, bunu dredd.yml aracılığıyla bağlarsınız ve şimdi tek görevi ilkini test edilebilir kılmak olan ikinci bir kod tabanına sahip olursunuz. Basit, salt okunur bir API için Dredd neredeyse yapılandırma gerektirmez. Oturum açma ve durum bilgisi olan uç noktaları olan gerçek bir API için kanca dosyası büyür ve başka bir adla yapıştırıcı koddur.

Örnek odaklı kapsayıcılıkta boşluklar vardır. Dredd, açıklamanızdaki mevcut örnekleri test eder. Bir uç noktanın belgelenmiş tek bir örnek yanıtı varsa, kontrol edilen de budur. Köşe durumları, hata yolları ve spesifikasyonda örnek olarak belirtilmeyen doğrulama kuralları, spesifikasyonu genişleterek veya daha fazla kanca yazarak eklemedikçe çalıştırılmaz. Kapsayıcılık, sürdürdüğünüz örnekler kadar iyidir, daha fazlası değil.

Entegre yol: spesifikasyon ve testler tek projede

Apidog'un yaptığı farklı bahis budur. API tanımı, elle senkronize ettiğiniz üçüncü bir dosya değildir; onu çalıştıran testler ve yapınızı denetleyen doğrulama ile aynı projede yaşayan doğruluk kaynağıdır. Şemayı değiştirin ve testler yeni şekli görür. Deponun bir köşesinde sürüklenen ayrı bir openapi.yaml veya spesifikasyon ile çalışan bir test arasında duran bir kanca dosyası yoktur.

API'yi bir kez tasarlar veya içe aktarırsınız. Apidog, OpenAPI 2 ve 3'ü okur, bir Swagger belgesini içe aktarır ve tek bir tıklamayla Postman koleksiyonlarını çeker. Uç noktalar, istek şemaları, yanıt şemaları ve örnek yanıtlar hepsi tek bir projede yer alır. Eğer zaten spesifikasyon öncelikli düşünüyorsanız, bu Dredd'in teşvik ettiği aynı disiplindir, sadece spesifikasyonun ayrı bir dosya olmaması farkıyla. Bu iş akışının daha derin sürümü spesifikasyon öncelikli API geliştirmede bulunur ve herhangi bir test çalışmadan önce spesifikasyon belgesini doğrulamak isterseniz, OpenAPI spesifikasyonlarını doğrulama bu adımı kapsar.

Doğrulamayı bu gerçek şemalara göre oluşturursunuz. Bir test senaryosu GET /orders/{id} çağrısı yaptığında, yanıtı Apidog'un bu uç nokta için zaten tuttuğu şemaya göre iddia edersiniz, elle kopyalanmış bir örneğe göre değil. Bu, Dredd'in gerçekleştirdiği spesifikasyon-uygulama kontrolüdür, tek farkla: kontrol edilen spesifikasyon, API'yi tasarladığınız aynı nesnedir, bu nedenle test paketinizle sessizce uyumsuz hale gelemez. Bu, üçüncü bir artefakt olmadan sözleşme testidir ve bu disiplinin daha geniş resmini görmek isterseniz, API sözleşme testi ve çift yönlü sözleşme testi her ikisi de daha derine iner.

Dredd'in bir kanca dosyasıyla, kimlik doğrulama belirteçleriyle, sıralamayla, veri doldurmayla ele aldığı kurulumu, çoğu web geliştiricisinin zaten yazdığı JavaScript'teki istek öncesi ve sonrası komut dosyalarıyla siz halledersiniz. Bir yapılandırma dosyası aracılığıyla bağlanan ayrı bir kancalar kod tabanı yoktur. Mantık, desteklediği testin yanında yaşar.

Apidog CLI'yi Kurma ve Çalıştırma

Çalıştırıcı, npm'e apidog-cli olarak yayınlanmıştır. Node.js'ye sahipseniz, ihtiyacınız olan her şeye sahipsiniz demektir:

npm install -g apidog-cli

İkili dosya apidog'dur, bu nedenle her çalıştırma apidog run ile başlar. Bir test senaryosunu çalıştırmak için bir erişim belirteci, senaryo kimliği ve ortam kimliği geçersiniz:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Bu kimlikleri elle yazmazsınız. Apidog'da test senaryosunu açın, CI/CD sekmesine gidin, komut satırı seçeneğini seçin ve bir erişim belirteci oluşturun. Apidog, senaryo ve ortam kimlikleri önceden doldurulmuş olarak tam apidog run komutunu sizin için oluşturur. Bir kez kopyalayın ve belirteci oradan parametrelendirin. Erişim belirtecini bir parola gibi kullanın: onu CI sisteminizde bir sır olarak saklayın ve buradaki her örneğin yaptığı gibi $APIDOG_ACCESS_TOKEN olarak referans gösterin.

Birden fazla senaryo çalıştırmak için, çalıştırıcıyı tek bir kimlik yerine bir klasöre veya bir test paketine yönlendirin ve raporlayıcılarınızı seçin:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

Bu -r bayrağı raporlayıcıları seçer. Apidog, okunabilir terminal çıktısı için cli'yi, bir derleme artefaktı olarak arşivlediğiniz kendi içinde bağımsız bir rapor için html'yi, neredeyse her CI panosunun geçme/kalma ağacına ayrıştırdığı XML için junit'i ve ham yapılandırılmış sonuçlar için json'ı destekler. Çalıştırıcının daha derinlemesine bir turunu istiyorsanız, tam bayrak listesi için apidog run --help komutunu çalıştırın.

Karşılaştırma

Bu tabloyu dürüstçe okuyun. Tamamen kendi kendine barındırılan, açık kaynaklı, hesapsız bir araç istiyorsanız ve ekibiniz bir kanca dosyasını sürdürmekte rahatsa, Dredd'in modeli temiz bir uyum sağlar ve sırf geçiş yapmak size hiçbir şey kazandırmaz. Entegre yolun durumu ise özeldir: spesifikasyonun ayrı duran üçüncü bir dosya olmasından sıkıldıysanız, bir kanca kod tabanına sahip olmak istemiyorsanız veya aynı projenin tasarımı, testi ve sözleşme kontrolünü birlikte ele almasını istiyorsanız.

CI'ya Entegre Etme

Apidog CLI başarılı olduğunda sıfır, başarısız olduğunda ise sıfırdan farklı bir çıkış koduyla sonlanır, bu nedenle tıpkı Dredd gibi herhangi bir CI sistemi bir derlemeyi buna bağlayabilir. Minimal bir GitHub Actions işi Node'a ve tek bir çalıştırma adımına ihtiyaç duyar:

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Tüm boru hattı budur. Bir Dredd işi benzer görünür, CLI'yı kurun, tek bir komut çalıştırın, ancak aynı zamanda spesifikasyon dosyanıza ve kanca dosyanıza da işaret edersiniz ve her ikisini de güncel tutarsınız. Doğrulama aynı şekilde çalışır; fark, oraya ulaşmak için kaç artefaktı sürdürdüğünüzdür.

Dredd'e başvurma nedeniniz gerçekten bir spesifikasyon ile bir hizmeti birbirine karşı dürüst tutmaksa, aynı mantık diğer araçlarda da ortaya çıkar. Ekipler, Swagger ve Postman'ın birbirinden uzaklaşmasıyla bunu yaşar ki Swagger ve Postman sapmasına karşı OpenAPI odaklı testler bunu kapsar, ve Java geliştiricileri bunu Rest Assured ile yaşar, burada alternatifler hikayesi benzerdir: modeli istemediğiniz bir katman ekleyen güçlü bir araç. IDE'nizden ayrılmak istemiyorsanız, Apidog'u VS Code uzantısı ile editörünüzden de çalıştırabilirsiniz.

Sıkça Sorulan Sorular

Apidog, Dredd kurulumunun doğrudan bir yedeği midir? Hayır, ve öyle olduğunu iddia etmez. dredd.yml ve hooks.js dosyalarınızı okuyup Apidog senaryoları üreten bir dönüştürücü yoktur. OpenAPI spesifikasyonunuzu içe aktarır ve doğrulamayı görsel düzenleyicide yeniden oluşturursunuz. Avantajı, bir kanca dosyasını ve dağınık bir spesifikasyonu sürdürmeyi bırakmanızdır; maliyet ise tek seferlik bir yeniden oluşturmadır. Eğer çalışan büyük ve olgun bir Dredd paketiniz varsa, bu yeniden oluşturma gerçek bir karardır, bedava bir öğle yemeği değil.

Apidog, Dredd gibi canlı uygulamayı doğrular mı? Evet. CLI, çalışan hizmetinize gerçek istekler gönderir ve gerçek yanıtları projenizdeki şemalara göre onaylar. Bu, Dredd'in gerçekleştirdiği spesifikasyon-uygulama kontrolü ile aynıdır. Fark, kontrol edilen şemanın API'yi tasarladığınız şema olmasıdır, bu nedenle testlerinizden sapmaz.

Dredd kancalarının izin verdiği şekilde kimlik doğrulama ve test kurulumunu hala yapabilir miyim? Evet. Apidog, JavaScript'te istek öncesi ve sonrası komut dosyalarını destekler, böylece kimlik doğrulama belirteçlerini alabilir, veri doldurabilir, yükleri dönüştürebilir veya kodda dinamik iddialar oluşturabilirsiniz. Mantık, yapılandırma aracılığıyla bağlanan ayrı bir kanca dosyasında değil, desteklediği senaryoda yaşar.

Dredd'in Apidog'un yapmadığı bir şey var mı? Birkaç şey. Dredd tamamen kendi kendine barındırılan ve hesapsız açık kaynak bir araçtır ve eski markdown açıklama formatı olan API Blueprint'i doğal olarak okur. Eğer hesapsız, tamamen yerel bir araç veya eski bir Blueprint dosyası kurulumunuz için merkeziyse, geçiş yapmadan önce bunu dikkatlice değerlendirin.

Apidog hangi formatları okur? OpenAPI 2 ve 3, Swagger belgeleri ve Postman koleksiyonları, hepsi tek bir projeye aktarılabilir. Önce format farklılıklarını anlamak isterseniz, Swagger ile OpenAPI karşılaştırması ve OpenAPI spesifikasyonuna genel bakış her ikisi de bunları açıklar.

Sonuç

Dredd temel fikri doğru anladı: API açıklamanız, çalışan hizmeti test ettiğiniz bir şey olmalı, sapıtan bir belge değil. Kendi kendine barındırılan, açık kaynaklı bir CLI istiyorsanız ve bir spesifikasyon dosyasını ve bir kanca dosyasını sürdürmekten memnunsanız, Dredd iyi bir seçimdir ve onu kullanmaya devam etmelisiniz.

Entegre yol, bu bakımın ortadan kalkmasını istediğiniz durumlar içindir. Apidog, spesifikasyonu, testleri ve doğrulamayı tek bir projede tutar, böylece kontrol ettiğiniz sözleşme, tasarladığınız sözleşme ile aynıdır ve tümünü sahiplenecek bir kanca kod tabanı olmadan apidog run komutuyla çalıştırır. Apidog'u indirin ve mevcut OpenAPI dosyanızı içe aktararak spesifikasyon-uygulama kontrolünü tek bir komutla nasıl çalıştığını görün.