Bir çekme isteği açtınız, dokümanlar sorunsuz bir şekilde oluşturuldu ve üç gün sonra bir ekip arkadaşınız size mesaj attı: Hazırlık sunucusu her isteği reddediyor çünkü OpenAPI dosyasında yeniden adlandırdığınız bir yolu işaret eden sarkan bir $ref var. Spesifikasyon editörde doğru görünüyordu. Swagger UI'da oluşturuldu. Sadece aslında geçerli değildi ve dağıtılmadan önce hiçbir şey bunu yakalamadı.
İşte bir Swagger komut satırı aracının tam da bunun için inşa edildiği iş: bozuk spesifikasyonları bir insan fark etmeden önce yakalamak. "swagger cli" ifadesi genellikle @apidevtools/swagger-cli'yi işaret eder; bu, iki komutu (validate ve bundle) olan küçük bir npm paketidir ve bir OpenAPI belgesini kontrol eder ve çoklu dosya spesifikasyonlarını tek bir dosyada birleştirir. Bu gerçekten faydalı bir araçtır ve bu kılavuz size onu doğru bir şekilde nasıl kullanacağınızı gösterir. Ayrıca nerede durduğunu da gösterir, çünkü bir spesifikasyonu doğrulamak, bir API'ye güvenmenin sadece ilk yarısıdır; ikinci yarısı gerçek istekler göndermek ve dönen veriyi doğrulamaktır, ve işte bu noktada Apidog CLI gibi bir çalıştırıcı devreye girer.
Yani bu aslında iki terminalin işi. İlk olarak, sözleşmenin sağlam olduğundan emin olmak için spesifikasyonu swagger-cli (veya halefi) ile lint ve bundle yapın. Ardından, uygulamanın sözleşmeyle eşleştiğini bilmek için çalışan API'ye komut satırından gerçek testler uygulayın. Her ikisini de ele alacağız, hangi aracın hangi işi yaptığını dürüstçe açıklayacağız ve her biri için kopyala-yapıştır komutları vereceğiz.
"swagger cli" aslında neyi ifade ediyor
"swagger" adlı tek bir resmi ikili yoktur. İsim birkaç farklı araca karşılık gelir ve hangisini kastettiğinizi bilmek, birçok karışıklığı önler.
@apidevtools/swagger-cliçoğu kişinin kastettiği pakettir. İkili dosyasıswagger-cli'dir ve iki şey yapar: bir OpenAPI veya Swagger 2.0 belgesini doğrular ve çok dosyalı bir spesifikasyonu tek bir dosyada toplar. Bu makalenin ilk yarısının odak noktası budur.swagger-codegen, bir spesifikasyondan istemci SDK'ları ve sunucu şablonları oluşturan ayrı, çok daha büyük bir SmartBear projesidir. Tamamen farklı bir iş; buna sonda değineceğiz.- Swagger UI ve Swagger Editor ise hiç CLI değildir. Bunlar tarayıcıda spesifikasyonları oluşturur ve düzenler. Formatı hala öğreniyorsanız, Swagger ve OpenAPI başlangıç kılavuzu doğru başlangıç noktasıdır.
Bu kılavuz, komut satırı çalışmaları hakkındadır: doğrulama, toplama, linting ve ardından test etme. Bunun yerine tasarım ve test platformlarının daha geniş bir incelemesini istiyorsanız, Swagger alternatifleri derlemesi GUI tarafını kapsar.
swagger-cli'yi Kurma
Araç bir npm paketi olarak gelir. Genel olarak yükleyin:
npm install -g @apidevtools/swagger-cli
Çözümlendiğini onaylayın:
swagger-cli --version
swagger-cli --help
Node.js tek sistem bağımlılığıdır. Node zaten kurulu olan herhangi bir makine veya CI imajı bunu çalıştırabilir. Genel olarak kurmak istemiyorsanız, npx @apidevtools/swagger-cli ... ile isteğe bağlı olarak çağırabilirsiniz, bu da geçici derleme çalıştırıcılarında kullanışlıdır.
Ona güvenmeden önce bilmeniz gereken bir şey: bakımcılar swagger-cli'yi kullanımdan kaldırılmış olarak işaretledi. README, az katkıda bulunan büyük bir kullanıcı tabanının bakım yükünü gerekçe göstererek bunu açıkça belirtiyor. Hala çalışıyor ve birçok pipeline bugün onu kullanıyor, ancak yeni projeler aktif olarak sürdürülen halefi olarak Redocly CLI'ye yönlendiriliyor. Bu geçişi aşağıdaki kendi bölümünde ele alıyoruz, böylece gözleriniz açık bir şekilde karar verebilirsiniz.
swagger-cli ile Bir Spesifikasyonu Doğrulama
Başlık komutu validate'dir. Spesifikasyon dosyanızı ona işaret edin:
swagger-cli validate openapi.yaml
Belge sağlamsa, tek satırlık bir onay ve 0 çıkış kodu alırsınız. Bir sorun varsa, sorunu açıklayan bir hata ve sıfır olmayan bir çıkış kodu alırsınız; bu, bir pipeline'da tam olarak istediğiniz şeydir.
validate, arka planda iki kontrol çalıştırır ve her ikisini de kapatabilirsiniz:
swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml
--no-schema, belgenizin doğru şekle sahip olduğunu onaylayan yapısal kontrol olan OpenAPI JSON Şemasına karşı doğrulamayı atlar. --no-spec, yinelenen işlem kimlikleri veya hiçbir yere işaret etmeyen bir $ref gibi şeyleri yakalayan anlamsal kontrol olan spesifikasyon kurallarının kendisine karşı doğrulamayı atlar. Çoğu zaman varsayılan olarak her ikisinin de açık olmasını istersiniz. Bayraklar, nadir durumlarda bir katmanın, kasıtlı olarak izin vermek istediğiniz bir şeyi işaret ettiği durumlar için mevcuttur.
validate'nin iyi yakaladığı şeyler: yanlış biçimlendirilmiş YAML, eksik gerekli alanlar, bozuk $ref işaretçileri ve bir spesifikasyonu ayrıştırılamaz hale getiren yapısal hatalar. Yapmadığı şey, ekibinizin stilini zorlamaktır. Hiçbir açıklaması olmayan, tutarsız adlandırmaya sahip ve örneksiz bir spesifikasyonu sevinçle geçirecektir, çünkü bunların hiçbiri OpenAPI kurallarını çiğnemez. Bu türden görüş odaklı bir kontrol için bir linter'a ihtiyacınız vardır, ki bu bir sonraki bölümdür.
Eğer sadece doğrulama için geldiyseniz, OpenAPI spesifikasyonlarını nasıl doğrulanacağına dair daha derinlemesine inceleme, bilmeye değer birkaç aracı ve uç durumu karşılaştırır.
Çoklu Dosya Spesifikasyonunu Bir Araya Getirme
Gerçek spesifikasyonlar nadiren tek bir dosyada bulunur. Şemaları bir components/ dizinine bölersiniz, bunlara $ref ile referans verirsiniz ve kök dosyayı okunabilir tutarsınız. Bu iyi bir hijyendir, ancak birçok alt seviye araç tek bir bağımsız belge ister. bundle komutu ağacı düzleştirir:
swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml
Bilmeye değer bayraklar:
-o, --outfile <dosya>sonucu stdout'a yazdırmak yerine bir dosyaya yazar.-t, --type <json|yaml>çıktı formatını ayarlar. Varsayılanıjson'dır, bu nedenle YAML çıktısı istiyorsanız-t yamlgeçirin.-r, --dereferenceharici dosyaları tek bir belgede toplamak yerine her$ref'i tamamen satır içine alır. Bu, kalan referansları olmayan daha büyük bir dosya üretir ve bazı tüketiciler bunu gerektirir.-f, --format <boşluklar>girintilemeyi kontrol eder, varsayılanı 2 boşluktur.-w, --wrap <sütun>uzun YAML dizelerini sarmak için satır uzunluğunu ayarlar.
Düz bundle ile --dereference arasındaki fark önemlidir. Normal bir bundle dahili $ref işaretçilerini korur ancak tüm ayrı dosyaları tek bir dosyada toplar, böylece belge taşınabilir olur. --dereference, her referansı satır içi nesnelere çözer, bu da dosya boyutunu artırır ancak hiçbir tüketicinin bir işaretçiyi çözmek zorunda kalmamasını garanti eder. Dağıtım için düz bundle'ı, yalnızca belirli bir araç talep ettiğinde dereferenced formu kullanın.
Yaygın bir desen, doğrulama ve bir araya getirmeyi bir derlemenin parçası olarak tek bir adımda yapmaktır:
swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json
&&, bundle'ın yalnızca doğrulama başarılı olursa çalışacağı anlamına gelir, böylece bozuk bir spesifikasyon asla bir derleme yapıtı üretmez.
swagger-cli'yi CI'ya Bağlama
Doğrulama, birisi hatırladığında değil, her değişiklikte çalıştığında en değerlidir. Hızlı bir geçit olarak pipeline'ınıza ekleyin. İşte geçersiz bir spesifikasyonda derlemeyi başarısız eden bir GitHub Actions adımı:
name: OpenAPI spesifikasyonunu doğrula
on:
pull_request:
paths:
- 'openapi.yaml'
- 'components/**'
jobs:
validate-spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Spesifikasyonu doğrula
run: npx @apidevtools/swagger-cli validate openapi.yaml
swagger-cli validate, kötü bir spesifikasyonda sıfır olmayan bir çıkış kodu döndürdüğü için adım kırmızıya döner ve çekme isteği başarısız bir kontrol gösterir. Ek yapılandırmaya gerek yoktur. paths filtresi, spesifikasyon değişmediğinde işin çalışmasını engeller, bu da CI dakikalarınızı azaltır.
Bu, bir API deposuna ekleyebileceğiniz en ucuz kalite kontrolüdür. Saniyeler sürer ve "dokümanlar yalan söyledi" türündeki hataların alt akışa ulaşmasını engeller.
Sadece doğrulama değil, linting'e ihtiyaç duyduğunuzda
Doğrulama tek bir soruyu yanıtlar: bu yasal bir OpenAPI belgesi mi? Linting daha zor bir soruyu yanıtlar: bu, ekibimizin standartlarına göre iyi bir OpenAPI belgesi mi? Bunlar aynı değildir ve swagger-cli yalnızca ilkini yapar.
Diyelim ki stil rehberiniz, her işlemin bir summary'ye sahip olmasını, her özelliğin bir description'a sahip olmasını ve her yolun kebab-case kullanmasını gerektiriyor. Bir spesifikasyon bu üçünü de ihlal edebilir ve yine de swagger-cli validate'i geçebilir, çünkü bu kuralların hiçbiri OpenAPI spesifikasyonunun bir parçası değildir. Bir linter, bunları kodlamanıza ve uygulamanıza olanak tanır.
Bu, ekiplerin, swagger-cli'nin kendisinin sizi yönlendirdiği sürdürülen halef olan Redocly CLI'ye geçmesinin ana nedenidir. Aynı doğrulama ve bir araya getirmeyi kapsar, ardından üzerine gerçek bir linting motoru ekler.
Redocly CLI'ye Geçiş
Geçiş küçüktür çünkü komut adları benzerdir. Halefi kurun:
npm install -g @redocly/cli
Doğrulama eşdeğeri lint'tir. Eski davranışı yakından eşleştirmek için, minimal kural setini genişletin:
redocly lint --extends=minimal openapi.yaml
Bunun yerine varsayılan kural setiyle çalıştırın ve daha güçlü bir önerilen kural setini zorlar, bu da linting değerinin ortaya çıktığı yerdir. Kuralları bir redocly.yaml dosyasında yapılandırır, her birini error veya warn olarak ayarlarsınız ve hatta kuruluşa özel kontroller için özel eklentiler yazabilirsiniz.
Bir araya getirme hemen hemen bire bir eşleşir:
redocly bundle openapi.yaml -o dist/openapi.yaml
Bayrak adları hafifçe değişir. swagger-cli'nin -o/--outfile'i --output olur, -t/--type'ı --ext olur ve -r/--dereference'ı -d/--dereferenced olur. Eski komut dosyalarınız kısa bayrakları kullandıysa, hızlı bir bul ve değiştir işlemi sizi hedefe ulaştırır. Spesifikasyon kontrol araçlarının daha geniş bir karşılaştırması için, en iyi OpenAPI doğrulama araçları dökümü Redocly'yi alternatiflerin yanına koyar.
Kısaca: yeni başlıyorsanız, Redocly CLI'ye yönelin. Çalışan mevcut bir swagger-cli adımınız varsa, acil bir durum yok, ancak ileriye giden yol açık ve yeniden adlandırma mekanik.
Bir spesifikasyon aracının kapsayamadığı yarım kısım
Şimdiye kadar tartıştığımız her aracın sınırı burada. swagger-cli validate, spesifikasyonunuzun iyi biçimlendirilmiş olduğunu onaylar. redocly lint, stilinize uyduğunu onaylar. Hiçbiri çalışan API'nize tek bir istek göndermez. Bir spesifikasyon kağıt üzerinde mükemmel olabilirken, uygulama bir 500 döndürebilir, vaat ettiği bir alanı atlayabilir veya bir sorgu parametresini tamamen göz ardı edebilir.
Bu boşluğu kapatmak, işlevsel test anlamına gelir: gerçek bir uç noktaya gerçek bir istek gönderin, ardından durum kodunu, yanıt gövdesini ve içindeki değerleri doğrulayın. Bu farklı bir araç kategorisidir ve Apidog'un iş akışına uyduğu yer burasıdır.
Apidog hepsi bir arada bir API platformudur. OpenAPI spesifikasyonunuzu içe aktarırsınız ve bu tek tanımlamadan, etkileşimli dokümanlar, bir sahte sunucu ve zincirleme test senaryoları elde edersiniz, hepsi çalışma alanından ayrılmadan. İçe aktarma doğrudandır; Swagger veya OpenAPI'yi içe aktarma ve çalıştırılabilir istekler oluşturma kılavuzu bunu açıklar ve elle inşa etmek yerine doğrudan spesifikasyondan tam test koleksiyonları oluşturabilirsiniz.
Terminal için önemli olan parça, apidog-cli npm paketi olarak yayınlanan komut satırı çalıştırıcısıdır. Onu kurar ve kaydedilmiş bir senaryoyu başsız olarak çalıştırırsınız:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
-t bayrağı test senaryosu kimliği, -e ortam kimliği ve -r cli, html, json veya junit gibi rapor formatlarını seçer. swagger-cli gibi, temiz bir durum koduyla çıkar, bu nedenle başarısız bir doğrulama pipeline'ı kırmızıya döndürür. swagger-cli'den farklı olarak, kontrol ettiği şey, onu açıklayan dosyanın şekli değil, API'nizin canlı davranışıdır. Eksiksiz bayrak referansı ve CI örnekleri için Apidog CLI kapsamlı kılavuzuna bakın veya mevcut seçenekler için apidog run --help komutunu çalıştırın. Bu ilk senaryoyu kurmak istiyorsanız, Apidog'u indirin, spesifikasyonunuzu içe aktarın ve çalıştırıcı komutu senaryonun CI/CD sekmesinden tek bir kopyalama işlemidir.
Tam bir terminal iş akışı
İki yarımı bir araya getirdiğinizde, sözleşmeyi ve uygulamayı sırayla kontrol eden bir pipeline elde edersiniz:
# 1. Spesifikasyon iyi biçimlendirilmiş ve stile uygun mu?
redocly lint --extends=minimal openapi.yaml
# 2. Tek bir dağıtılabilir belge üretin.
redocly bundle openapi.yaml -o dist/openapi.yaml
# 3. Çalışan API gerçekten sözleşmeyle eşleşiyor mu?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
Birinci adım, yanlış biçimlendirilmiş veya stile uygun olmayan bir spesifikasyonda hızla başarısız olur. İkinci adım, dokümanlarınızın ve SDK oluşturucularınızın tükettiği yapıyı üretir. Üçüncü adım, gerçek trafik gönderir ve yanıtları doğrular, böylece başarılı bir derleme hem sözleşmenin hem de arkasındaki kodun sağlam olduğu anlamına gelir. Her adım başarısızlık durumunda sıfır olmayan bir çıkış kodu döndürür, bu nedenle tüm zincir, Node kurulu herhangi bir CI çalıştırıcısına ekleyebileceğiniz tek bir geçittir.
Bugünkü testleriniz, sessizleşen bir spesifikasyon uyumluluk aracına dayanıyorsa, Dredd olmadan bir API'yi spesifikasyonuna göre doğrulama yazısı, aynı sözleşme-uygulama fikrini farklı bir açıdan ele alıyor.
swagger-codegen hakkında bir not
"swagger cli" arayan kişiler bazen aslında farklı bir işleve sahip farklı bir araç olan swagger-codegen'i isterler. Bu araç bir OpenAPI spesifikasyonunu okur ve onlarca dilde istemci SDK'ları, sunucu şablonları ve dokümantasyon oluşturur. Yayınlanmış bir spesifikasyondan yazılı bir istemciyi önyüklemek için gerçekten kullanışlıdır ve Swagger ailesindeki en yetenekli kod oluşturma seçeneği olduğunu söylemek adildir.
Bu makalede ele alınan anlamda doğrulama, linting veya test yapmaz. Oluşturma, zaten sağlam bir spesifikasyonunuz olduğunu varsayar; girdi bozuksa, çıktı da aynı şekilde bozuk olur. Dolayısıyla, bir kod oluşturma iş akışında bile, önünde hala bir doğrulama veya lint adımı istersiniz. Araçlar birbirini değiştirmek yerine birbirini tamamlar.