Eğer buraya npm install -g @apidevtools/swagger-cli komutunu çalıştırdıktan ve uyarıları fark ettikten sonra geldiyseniz, işte kısa versiyonu: araç artık sürdürülmüyor. GitHub'daki swagger-cli deposu, "büyük bir kullanıcı tabanının beklentilerini karşılamaya çalışmanın ve çok az katkı almanın bakım yükü" gerekçesiyle açıkça kullanımının sona erdiğini belirtiyor. README'nin kendisi sizi Redocly CLI'a halefi olarak yönlendiriyor.
Yani bir yedeğe ihtiyacınız var. Bu, özellikle validate ve bundle yapan swagger-cli terminal aracıyla ilgilidir. Eğer aslında Swagger Editor, SwaggerHub veya daha geniş tasarım paketini kastediyorsanız, bunun yerine API'nizi test eden 7 Swagger alternatifi yazısını okuyun.
Önce swagger-cli'nin ne yaptığına bakalım, sonra şimdi ne kullanacağınıza dair dürüst kısa listeyi inceleyelim.
swagger-cli aslında ne yaptı
Hassas olmakta fayda var, çünkü doğru yedekleme, neyi kullandığınıza bağlıdır.
swagger-cli'nin tam olarak iki komutu vardı:
# Bir Swagger 2.0 / OpenAPI 3.0 tanımını şemaya göre doğrular ve $ref'leri kontrol eder
swagger-cli validate openapi.yaml
# $ref işaretçilerini takip eder ve çok dosyalı bir tanımı tek bir dosyada birleştirir
swagger-cli bundle openapi.yaml -o bundled.json
bundle komutunun küçük bir seçenek kümesi vardı: bir dosyaya yazmak için -o/--outfile, JSON veya YAML seçmek için -t/--type, her $ref'i tamamen satır içi yapmak için -r/--dereference ve girinti için -f/--format.
Tüm araç buydu. Yapıyı doğruladı ve çok dosyalı spesifikasyonları bir araya getirdi. Stil kurallarıyla lint etmedi, doküman oluşturmadı, test çalıştırmadı veya hiçbir şeyi taklit etmedi. swagger-cli'nin spesifikasyonunuzu "lint ettiğini" iddia edenleri okursanız, yanılıyorlar; sadece tanımınızı OpenAPI şemasına göre kontrol etti ve referansları çözdü. Bu kapsamı aklınızda bulundurun, çünkü bazı yedekler çok daha fazlasını yapar ve bunu isteyip istemediğiniz size kalmış.
Kısa liste
Üç araç, swagger-cli'ye başvurmanız için neredeyse her nedeni kapsıyor, ayrıca bahsetmeye değer birkaç uzman. İşte dürüst özet.
Redocly CLI: resmi halef ve en yakın 1:1 değiştirme
Redocly CLI (@redocly/cli, ikili redocly) açık kaynaklıdır ve swagger-cli'nin kendi README'sinin sizi yönlendirdiği araçtır. Redocly, swagger-cli'den geçiş kılavuzu bile yayınlamaktadır. Amacınız bir terminal doğrulayıcı ve birleştirici olarak hazır bir çözümse, buradan başlayın.
swagger-cli'yi kurduğunuz gibi kurun:
npm install -g @redocly/cli@latest
# veya kurmadan çalıştırın
npx @redocly/cli@latest lint openapi.yaml
Eşleştirme temiz. swagger-cli'nin validate komutu, spesifikasyonunuzu kontrol eden ve yapılandırılabilir stil kuralları uygulayan redocly lint haline gelir. swagger-cli'nin bundle komutu ise redocly bundle olur:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
İşte bundle bayrağı eşleştirmesi yan yana:
| swagger-cli | Redocly CLI | Amaç |
|---|---|---|
-o, --outfile |
--output (veya -o) |
Bir dosyaya yaz |
-t, --type |
--ext (json, yaml, yml) |
Çıktı formatı |
-r, --dereference |
-d, --dereferenced |
Tüm $ref'leri tamamen satır içi yap |
Bilmeniz gereken bir şey: redocly lint varsayılan olarak swagger-cli'nin validate'inden daha fazlasını yapar. Sadece bir şema kontrolü değil, bir stil rehberi kural seti uygular. Eğer swagger-cli'nin size verdiği basit yapısal doğrulamayı istiyorsanız, sadece spec kuralı ile bir redocly.yaml yapılandırın, ardından redocly lint openapi.yaml komutunu çalıştırın. Bu kural seti davranışı, bir dezavantajdan çok Redocly'nin imzası niteliğindeki gücüdür; terminal tabanlı yönetişim isteyen ekiplerin beğenmesinin nedeni budur. Kural setlerini (minimal, recommended, recommended-strict, spec) ayarlayabilir veya özel kurallar yazabilirsiniz. Bunun diğer lint araçlarıyla nasıl uyduğunu görmek için en iyi OpenAPI lint aracı kurulumuna bakın.
Redocly CLI ayrıca swagger-cli'nin iki komutunun ötesine de geçer. Tek bir tanımı çok dosyalı bir yapıya split edebilir (bundle'ın tersi), birden çok dosyayı join edebilir (deneysel) ve bağımsız Redoc HTML dokümanları oluşturabilir:
redocly build-docs openapi.yaml -o docs.html
Ne yapmaz: API testleri çalıştırmaz veya bir mock sunucu barındırmaz. Bu, kod odaklı, terminal tabanlı bir lint/bundle/docs aracıdır ve mükemmeldir. Eğer ihtiyacınız olan tek şey buysa, okumayı bırakıp bugün geçiş yapabilirsiniz.
Apidog: doğrulamadan ve birleştirmeden daha fazlasını istediğinizde
İşte dürüst bir yeniden çerçeveleme. swagger-cli, doğrulamak ve birleştirmek için çalıştırdığınız statik bir betikti. Ancak çoğu ekip için doğrulama ve birleştirme amaca ulaşmak için birer araçtır. Spesifikasyonun doğru olması için doğrularsınız, taşınabilir olması için birleştirirsiniz, sonra onu taklit edersiniz, test edersiniz ve belgelersiniz. swagger-cli, bu sonraki adımları diğer araçlara bıraktı.
Apidog bu boşluğu kapatıyor. Tek bir çalışma alanında tasarım, mock, test ve dokümanları içeren hepsi bir arada bir API platformudur; import, export ve CI test çalıştırmalarını yöneten bir CLI ile birlikte. swagger-cli size bir dosya verirken, Apidog o dosyadan oluşturulmuş canlı bir çalışma alanı sunar.
swagger-cli kas hafızanıza en doğrudan uyan iki komut import ve export'tur. Önce CLI'ı kurun ve kimlik doğrulaması yapın:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
Jetonu Apidog uygulamasından veya web'den alırsınız: avatar, sonra Hesap Ayarları, sonra API Erişim Jetonu. Bu, ~/.apidog/config.toml içinde saklanır, bu yüzden asla yazdırmayın veya commit etmeyin.
İçeri aktarma (Import), doğrulama adımınızdır. Bir tanımı bir projeye alır ve çok dosyalı $ref'leri birleşik kaynaklara dönüştürür. Dosya bozuksa, içeri aktarma bunu yüzeye çıkarır:
apidog import --project 123456 --format openapi --file ./openapi.json
İçeri aktarma, OpenAPI'nin ötesinde Postman, HAR, Insomnia, WSDL ve JSON Şema dahil olmak üzere uzun bir format listesini kabul eder, bu da kaynaklarınız karıştığında kullanışlıdır.
Dışa aktarma (Export), bir bonus ile birlikte paketleme adımınızdır. Tek bir birleştirilmiş dosya çıkarır ve çıkışta OpenAPI sürümünü seçersiniz. Bu, tek bir komutta paketleme ve isteğe bağlı bir spesifikasyon yükseltmesi anlamına gelir:
# Tek seferde paketleme ve OpenAPI 3.1'e yükseltme
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Veya bağımsız HTML dokümanları yayınlayın
apidog export --project 123456 --format html --output ./docs.html
CI için Apidog, swagger-cli'nin hiç sahip olmadığı adımı ekler: testleri çalıştırmak.
# Birden çok rapor formatıyla CI'da bir test senaryosu çalıştırın
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# Veya dışa aktarılmış bir koleksiyon dosyasından tamamen çevrimdışı çalıştırın
apidog run ./collection.apidog-cli.json
CLI ayrıca endpoint, schema, mock, environment, branch, test-suite ve test-report dahil olmak üzere proje kaynaklarını doğrudan yönetir. Kurulum detayları ve her bir bayrak için Apidog CLI kapsamlı kılavuzuna ve resmi Apidog CLI dokümanlarına bakın.
Şimdi dürüst sınırlamalar, çünkü uyum abartıdan daha önemlidir. Apidog'un CLI'sı içe aktarma sırasında yapıyı doğrular, ancak Redocly'nin lint komutunun yaptığı gibi yapılandırılabilir, kod odaklı bir stil rehberi linter'ı özel kural setleriyle sunmaz. Bir apidog lint komutu yoktur ve CLI aracılığıyla Spectral tarzı özel kurallar yazamazsınız. Ayrıca split veya join da yoktur. Apidog öncelikli olarak GUI odaklıdır: tasarım, mock, görsel test oluşturma ve dokümanlar öncelikle masaüstü veya web uygulamasında oluşturulur; CLI ise bir projeye karşı içe aktarma, dışa aktarma, CI test çalıştırmaları ve kaynak yönetimini üstlenir. Ve Apidog, açık kaynak yerine freemium'dur, bu nedenle Redocly CLI ve Spectral'den farklı bir modeldir.
Spectral: CI'da saf, özelleştirilebilir linting
Eğer swagger-cli'den gerçekten istediğiniz şey, pipeline'ınızda katı, iddialı doğrulama ise, özel linter Stoplight'tan Spectral'dır. Açık kaynaklıdır ve tek bir iş için tasarlanmıştır: OpenAPI (ve diğer JSON/YAML) belgelerine özelleştirilebilir bir kural seti uygulamak.
Spectral, her çekme isteğinde kendi kurallarınızla şirket stilini kod olarak zorlamak istediğinizde parlar. Paketleme yapmaz, doküman oluşturmaz ve uç noktaları test etmez; sadece lint eder. Bir paketleyici ile eşleştirirseniz, swagger-cli'nin yaptığının odaklanmış bir versiyonunu, artı gerçek yönetişimi yeniden oluşturmuş olursunuz. Spectral OpenAPI linting rehberimiz kural setleri yazmayı anlatır ve CI'da OpenAPI doğrulaması bunu bir pipeline'a bağlamayı kapsar.
Kısaca: openapi-generator ve vacuum
İki araç daha karşımıza çıkıyor, işte doğru, kısa versiyonu. openapi-generator bir kod ve istemci üretecidir; eğer paketleme nedeniniz bir üreteci beslemek idiyse, spesifikasyonları doğrudan tükettiği için ayrı bir paketleme adımına hiç ihtiyacınız olmayabilir. vacuum, Go dilinde yazılmış hızlı, Spectral uyumlu bir OpenAPI linter'ıdır; büyük monorepolarda lint hızının önemli olduğu durumlarda iyi bir seçimdir. İkisi de tek başına genel bir doğrulama artı paketleme yedeği değildir, ancak ikisi de belirli ihtiyaçlara uygundur.
Karşılaştırma tablosu
swagger-cli kullanıcılarının önem verdiği yetenekler açısından seçenekler şu şekilde sıralanıyor.
| Araç | Doğrula | Paketle | Lint Kuralları | Dokümanlar | Taklit Et (Mock) | Test Et | Açık Kaynak | En İyisi |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | Evet | Evet | Hayır | Hayır | Hayır | Hayır | Evet (kullanımdan kaldırıldı) | Yeni hiçbir şey; bakımı yapılmıyor |
| Redocly CLI | Evet (lint) |
Evet | Evet (yapılandırılabilir) | Evet (Redoc HTML) | Hayır | Hayır | Evet | Yönetişim özellikli, hazır bir terminal doğrulama/paketleme değişimi için |
| Apidog | Evet (içe aktarımda) | Evet (dışa aktarımda, OAS yükseltme ile) | Sadece yapısal, özel kural setleri yok | Evet (uygulama + dışa aktarım) | Evet | Evet (CLI çalıştırma) | Hayır (freemium) | Tüm API yaşam döngüsü için tek bir araç |
| Spectral | Evet (lint tabanlı) | Hayır | Evet (özel kural setleri) | Hayır | Hayır | Hayır | Evet | CI'da katı, özelleştirilebilir linting için |
| vacuum | Evet (lint tabanlı) | Hayır | Evet (Spectral uyumlu) | Hayır | Hayır | Hayır | Evet | Büyük spesifikasyonlarda hızlı linting için |
Öneri
Bu, "her şey harika, favorinizi seçin" durumu değil. Neredeyse herkesi kapsayan iki net yol var.
Hazır bir değiştirme istiyorsanız Redocly CLI'ı seçin. Resmi halefidir, açık kaynaklıdır ve geçiş neredeyse mekaniktir: validate'ten lint'e, bundle'dan bundle'a, yukarıdaki bayrak eşleştirmesi ile. Eğer iş akışınız gerçekten sadece "terminalden doğrulama ve paketleme" ise ve daha sonra araç değiştirmeden yönetişim kuralları eklemek isterseniz, Redocly açık ara en iyi seçimdir. Sizi kod odaklı ve terminal tabanlı tutar, ki bu tam da swagger-cli'nin yaşadığı yerdi.
Eğer doğrulama ve paketleme sadece başlangıçsa Apidog'u seçin. Çoğu ekip, bir spesifikasyonu sırf kendisi için doğrulamaz. Onu doğrularlar, sonra birilerinin üzerine inşa etmek için bir mock'a ihtiyacı olur, başkası testler yazar ve birileri dokümanların sorumluluğunu alır. swagger-cli ilk adımda durdu ve gerisini Spectral, bir paketleyici, Postman ve Newman'dan bir araya getirmenizi sağladı. Apidog, import (doğrulama), export (paketleme artı bir OAS sürüm yükseltme), mock, test ve dokümanları tek bir çalışma alanına getirir, CI'da yer alması gereken kısımlar için bir CLI ile. Artık statik, bakımı yapılmayan bir betiği takip etmeyi bırakır ve tüm spesifikasyonu, paketlendikten sonra da kullanışlı kalacağı bir yere taşırsınız.
Bunlar farklı paradigmalar, aynı şeyin rekabet eden versiyonları değil. Redocly CLI, saf bir şekilde terminalden çalıştırdığınız hafif, yapılandırma odaklı bir uzmandır. Apidog ise, yetenekli bir CLI'ya sahip olan hepsi bir arada bir platformdur. Yaşam döngüsünün ne kadarını tek bir araçta istediğinize göre seçin ve dürüst olun: eğer sadece terminalde lint etmek ve paketlemek istiyorsanız, Redocly daha yalın ve ücretsizdir.
Yaşam döngüsü yaklaşımını denemek isterseniz, Apidog'u indirin ve mevcut bir spesifikasyonu içe aktarın; başlamak ücretsizdir, kredi kartı gerekmez ve paketlenmiş, sürümlü çıktınızı birkaç dakika içinde görebilirsiniz.
Sıkça Sorulan Sorular
swagger-cli hala sürdürülüyor mu?
Hayır. swagger-cli GitHub deposu, büyük bir kullanıcı tabanına karşı düşük katkı nedeniyle kullanımının sona erdiği ve artık sürdürülmediği şeklinde işaretlenmiştir. Hala kurulup çalışsa da, düzeltme veya güncelleme almayacaktır, bu nedenle bir geçiş planlayın.
swagger-cli'nin yerini ne aldı?
Projenin kendi README'si, Redocly CLI'ı halef olarak işaret ediyor. redocly lint, swagger-cli validate'in ve redocly bundle, swagger-cli bundle'ın yerini alıyor. Redocly, özel bir geçiş kılavuzu bile yayınlıyor. Doğrulama ve paketlemeden daha fazlasını istiyorsanız, Apidog import, export, mock, test ve dokümanları tek bir yerde kapsar.
Apidog ücretsiz mi?
Apidog freemium'dur. Kredi kartı gerektirmeyen, ücretsiz bir katmanı vardır; daha büyük ekipler ve gelişmiş ihtiyaçlar için ücretli planlar mevcuttur. Açık kaynak değildir, bu da açık lisanslama sizin için bir gereklilikse Redocly CLI ve Spectral'den temel farkıdır.
swagger-cli iş akışımı aynen koruyabilir miyim?
En yakın olan Redocly CLI'dır. swagger-cli'nin basit yapısal validate komutunu yansıtmak için, sadece spec kuralı ile bir redocly.yaml kurun ve redocly lint komutunu çalıştırın. Paketleme için komutlar ve bayraklar neredeyse bire bir eşleşir. Orijinal aracın kapsamına daha derinlemesine bakmak için, terminalden swagger-cli nasıl kullanılır bölümüne bakın.