Apidog CLI vs Redocly CLI: Hangi API CLI'ı Kullanmalısınız?

Bu araçların her ikisi de terminalinizde çalışır, her ikisi de OpenAPI konuşur ve bir ekip API spesifikasyonları için komut satırı iş akışı istediğinde her ikisi de ortaya çıkar. Çakışma burada sona erer. Birbirine komşu sorunları zıt yönlerden çözerler ve yanlış olanı seçmek, ya testleri çalıştırmayan bir linter ile mücadele etmek ya da hızlı bir yapısal kontrol istediğinizde bir platforma yönelmek anlamına gelir.

Bu, Apidog CLI ile Redocly CLI'ın doğrudan, komut düzeyinde bir karşılaştırmasıdır. Asılsız iddialar yok. Redocly'nin CLI'ı gerçekten iyi bir açık kaynak yazılımdır ve herhangi bir karar verilmeden önce nerede öne çıktığını tam olarak göreceksiniz.

TL;DR Kararı

Birbiriyle çakışan ancak farklı sorunları çözerler.

Redocly CLI (@redocly/cli, ikili dosya redocly) kod öncelikli bir OpenAPI uzmanıdır: özel kural setleriyle lintleme yapar, çok dosyalı spesifikasyonları paketler (bundle), böler ve birleştirir, ve bağımsız HTML dokümanları oluşturur. Açık kaynaklıdır, konfigürasyon odaklıdır ve terminalde yerel olarak çalışır. Eğer spesifikasyonunuz doğruluk kaynağıysa ve git'te yaşıyorsa, bu, komut satırından çalıştırdığınız bir yönetim aracıdır.

Apidog CLI (apidog-cli, ikili dosya apidog) hepsi bir arada bir API platformunun komut satırı arayüzüdür. Bir projeye karşı tanımları içe ve dışa aktarır ve CI'da JUnit ve HTML raporlarıyla API test senaryolarını çalıştırır. Aynı spesifikasyonun ayrı araçlardan bir araya getirilmek yerine tek bir çalışma alanında sahte (mock), test edilmesi ve belgelenmesi gerektiğinde yerini alır.

Tamamen terminalden çalıştırdığınız hafif, açık kaynaklı bir linter, paketleyici (bundler) ve belge oluşturucu istiyorsanız Redocly CLI'ı seçin. Tüm API yaşam döngüsü için tek bir araca sahip olmayı tercih ediyorsanız Apidog'u seçin. Ayrıca yan yana da çalışabilirler ve son bölüm nasıl çalıştığını açıklar.

İki farklı felsefe

Redocly CLI dosya merkezli ve kod önceliklidir. Disk üzerindeki OpenAPI belgesi üzerinde işlem yaptığınız şeydir. Her komut, redocly lint, redocly bundle, redocly build-docs, bir dosya yolunu alır ve işini yerel olarak, herhangi bir hesap veya sunucu olmadan yapar. Davranış, spesifikasyonun yanına depoya eklediğiniz bir redocly.yaml yapılandırması tarafından şekillendirilir. Bu model, API açıklamasını kaynak kodu olarak gören ekiplere uyar: çekme isteklerinde incelenir, CI'da korunur, diğer her şey gibi sürümlendirilir. OpenAPI Spesifikasyonu sözleşmedir ve Redocly CLI, bunu denetleyen araç zinciridir.

Apidog proje merkezli ve platform önceliklidir. Uç noktaları tasarlar, sahte sunucular (mock servers) oluşturur ve test senaryolarını masaüstü veya web uygulamasında görsel olarak yazarsınız; CLI ise bu işin bir alt kümesi için başsız bir arayüzdür. Çoğu CLI komutu, sunucudaki bir Apidog projesine karşı çalışır; bu proje bir proje kimliği ile tanımlanır ve bir erişim belirteci ile doğrulanır. Spesifikasyon, yerinde lintleme yaptığınız bağımsız bir dosya değildir; aynı zamanda sahte olarak kullanılabileceği (mocked), test edilebileceği ve belge olarak yayınlanabileceği canlı bir çalışma alanına aktarılır. Tek bir ortam, birçok iş.

Her iki felsefe de yanlış değildir. Farklı ekiplere uygunlardır. Dürüst ayrım şudur: Redocly size spesifikasyon yönetimi için odaklanmış, açık kaynaklı bir CLI sunarken, Apidog size daha geniş bir platforma erişim sağlayan bir CLI sunar.

Komut komut

İşte önemli kısım, görev görev eşleştirildi. Aşağıdaki her komut gerçektir; hiçbir şey uydurulmadı.

Bu satırlardan bazıları açık sözlü bir notu hak ediyor, çünkü fark gerçek ve bu not olmadan makale dürüst olmazdı.

Lintleme Redocly'nin ana alanıdır, Apidog'un değil. Redocly CLI, OpenAPI, AsyncAPI, Arazzo ve Open-RPC'yi yapılandırılabilir kural setlerine göre lintler ve kendi kurallarınızı yazabilirsiniz. Apidog, bir tanımın yapısını içe aktardığınızda doğrular, ancak apidog lint komutu, redocly.yaml tarzı bir yapılandırma ve CLI aracılığıyla özel stil rehberi kuralları yazmanın bir yolu yoktur. Amacınız terminalde uygulanan kod öncelikli bir stil rehberi ise, Redocly doğru araçtır. Apidog burada rekabet etmez ve aksini söylemek yanlış olur.

Bölme (split) ve birleştirme (join) Redocly'ye aittir. redocly split, tek bir açıklamayı çok dosyalı bir yapıya ayırır ve redocly join (deneysel) birkaç dosyayı tek bir dosyada birleştirir. Apidog'da bu komutların hiçbiri yoktur. İçe aktarımı, çok dosyalı $ref'leri birleşik kaynaklara çözer ve dışa aktarımı tek bir birleştirilmiş dosya çıkarır, ancak bu, bağımsız dosyalar üzerinde çalıştırdığınız bağımsız bir bölme/birleştirme aracıyla aynı şey değildir.

Test çalıştırma ve sahte sunucular (mocking) Apidog'a aittir. Redocly CLI API testlerini yürütmez ve bir sahte sunucu barındırmaz; bu, tasarım gereği kapsamı dışındadır. Apidog, apidog run ile test senaryolarını başsız (headless) olarak çalıştırır ve ardışık düzeniniz (pipeline) için JUnit, HTML, JSON ve CLI raporları üretir ve sahte sunucu özelliği (uygulamada yazılır, CLI'dan yönlendirilmez) platformun birinci sınıf bir özelliğidir.

Her ikisi de terminalden HTML belgeleri oluşturur. redocly build-docs bağımsız bir Redoc HTML dosyası üretir. apidog export --format html projenizden bir HTML belge dosyası yazar. Farklı motorlar, aynı terminal sonucu.

Gerçek Redocly CLI komutları

Genel olarak yükleyin veya yüklemeyi atlayarak npx aracılığıyla çalıştırın:

npm install -g @redocly/cli@latest
# veya, global yükleme olmadan:
npx @redocly/cli@latest lint openapi.yaml

Bir spesifikasyonu lintleyin. Bir redocly.yaml mevcutsa, bu seçtiğiniz kural setini (minimal, recommended, recommended-strict, spec veya özel kurallar) uygular:

redocly lint openapi.yaml

Sadece, eskimiş swagger-cli'nin yaptığı türden, düz yapısal doğrulama istiyorsanız, redocly.yaml dosyasını yalnızca spec kuralıyla yapılandırın ve aynı redocly lint komutunu çalıştırın. Redocly, Redocly CLI onun adlandırılmış halefi olduğu için swagger-cli'dan geçiş rehberi yayınlar. swagger-cli deposu şimdi aynı nedenden ötürü bir kullanımdan kaldırma bildirimi taşıyor; o eski araç sadece doğrulama ve paketleme yapıyordu, asla stil kurallarıyla lintleme yapmıyordu.

Her $ref'i takip ederek çok dosyalı bir tanımı tek bir dosyada paketleyin (bundle):

redocly bundle openapi.yaml --output bundled.json

Swagger-cli'dan geliyorsanız, bayraklar sorunsuz bir şekilde eşleşir: -o/--outfile, --output olur, -t/--type, --ext (json, yaml veya yml) olur ve -r/--dereference, -d/--dereferenced olur.

Redoc ile bağımsız HTML dokümantasyonu oluşturun:

redocly build-docs openapi.yaml -o docs.html

Tek bir açıklamayı, paketlemenin tersi olan çok dosyalı bir düzene bölün:

redocly split openapi.yaml --outDir ./split-spec

Redocly'nin bu kategorideki diğer araçlarla nasıl karşılaştırıldığına dair daha geniş bir bakış için, OpenAPI linter kurulum kılavuzu Spectral, Redocly ve Vacuum'u yan yana incelerken, Redocly alternatifleri derlemesi özellikle belge platformunu ele almaktadır.

Gerçek Apidog CLI komutları

CLI'yı yükleyin ve uygulamadan bir jetonla doğrulayın (avatar, ardından Hesap Ayarları, ardından API Erişim Jetonu):

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

Jeton ~/.apidog/config.toml konumuna kaydedilir. Yazdırmayın veya commit etmeyin.

Bir tanımı bir projeye aktarın. Bu, yapıyı doğrular ve çok dosyalı $ref'leri birleşik kaynaklara çözerek içeri alır:

apidog import --project 123456 --format openapi --file ./openapi.json

İçe aktarma, OpenAPI'den daha fazlasını kabul eder: Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema ve Apidog'un kendi formatı.

Tek bir birleştirilmiş dosyayı dışa aktarın, isteğe bağlı olarak OpenAPI sürümünü yükselterek. Bu, tek adımda paketleme (bundle) ve isteğe bağlı bir sürüm yükseltmesidir:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

HTML belgelerini doğrudan projeden dışa aktarın:

apidog export --project 123456 --format html --output ./docs.html

CI'da bir test senaryosu çalıştırın ve ardışık düzeninizin okuyabileceği raporlar yayınlayın:

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

Dışa aktarılmış bir koleksiyon dosyasından tamamen çevrimdışı da çalıştırabilirsiniz, proje veya jetona gerek yok:

apidog run ./collection.apidog-cli.json

--out-dir, -n/--iteration-count, -d/--iteration-data ve --env-var dahil olmak üzere tam bayrak referansı Apidog CLI tam kılavuzunda bulunur. Resmi Apidog CLI dokümantasyonu kurulumu ve her kaynak komutunu kapsar. Koşucudan koşucuya CI karşılaştırması için Apidog CLI Newman'a karşı ve Bruno CLI Apidog CLI'a karşı başlıklı makalelere bakın.

Redocly CLI ne zaman seçilmeli

Spesifikasyon sizin doğruluk kaynağınız olduğunda ve onu kod olarak yönetmek istediğinizde Redocly CLI'a başvurun.

Özel kurallara sahip gerçek bir linter istersiniz. Redocly'nin lint komutu ve redocly.yaml yapılandırması ayırt edici özelliğidir: yerleşik bir kural seti seçin veya kendinizinkini yazın ve her commit'te adlandırma kurallarını, zorunlu alanları ve şirket stilini uygulayın. Apidog'un CLI'ında buna uyan hiçbir şey yoktur. Eğer terminal tabanlı stil yönetimi işiniz ise, Redocly cevaptır.

Hesapsız açık kaynak istersiniz. CLI tamamen makinenizde veya CI çalıştırıcınızda çalışır. lint, bundle, split veya build-docs için giriş, jeton veya sunucu çağrısı yok. Hava boşluklu ortamlar veya katı veri işleme kuralları için bu, Redocly'nin karşıladığı ve bir platform CLI'ının genellikle karşılamadığı zorlu bir gereksinimdir.

Hafif, odaklanmış bir araç zinciri istersiniz. Eğer ihtiyacınız olan tek şey terminalden lintleme, paketleme (bundle), bölme (split), birleştirme (join) ve HTML belgeleri ise, Redocly tam olarak bunu yapar ve fazlasını yapmaz. Sıfır kurulumla yükleyebilir veya npx aracılığıyla çalıştırabilirsiniz. Tam komut seti Redocly CLI belgelerinde ve npm paket sayfasında bulunur.

Apidog ne zaman seçilmeli

Spesifikasyon, ayrı araçlardan bir araya getirmek istemeyeceğiniz daha büyük bir yaşam döngüsünün bir parçası olduğunda Apidog'a başvurun.

Tasarım, sahte sunucu (mock), test ve belgeleri tek bir yerde istersiniz. CLI spesifikasyonunuzu içe aktarır, seçtiğiniz OpenAPI sürümünde temiz bir birleştirilmiş dosya dışa aktarır ve CI'da test senaryolarını çalıştırır. Aynı proje size görsel tasarım, bir sahte sunucu ve yayınlanmış dokümantasyon da sağlar; hepsi tek bir tanımı paylaşır. Bir linter, bir sahte sunucu aracı, bir test çalıştırıcısı ve bir belge oluşturucuyu bir araya getirme zahmetinden kurtulursunuz.

Kullanılabilir raporlarla ardışık düzeninizde test yürütme istersiniz. apidog run, CI gösterge tablonuz için JUnit XML, ayrıca HTML ve JSON yapıları üretir ve bir test başarısız olduğunda sıfır olmayan bir kodla çıkar. Redocly hiç test çalıştırmaz, bu nedenle CI test geçidi listenizdeyse, Apidog burada devreye girer. CI'da OpenAPI doğrulamasındaki desenler, aynı ardışık düzende bir test çalışmasıyla doğal olarak eşleşir.

Tüm bir ekip için tek bir doğruluk kaynağı istersiniz. Kaynaklar, tasarımcıların, test uzmanlarının ve yazarların hepsinin üzerinde çalıştığı bir Apidog projesinde yaşar. CLI, paylaşılan bu çalışma alanının üzerinde bir otomasyon arayüzüdür ve spesifikasyon dosyalarını birbirine aktarmak yerine bir platformda işbirliği yapmayı tercih eden ekiplere uygundur.

Takip etmek için Apidog'u indirin. Başlamak ücretsizdir, kredi kartı gerekmez.

Birbirini tamamlayabilirler

Bu kesinlikle ya o ya da bu değildir ve öyleymiş gibi davranmak en pratik kurulumu kaçırmak olur.

Güçlü bir iş akışı, her çekme isteğinde stil rehberinizi uygulayan bir lint geçidi olarak CI'da Redocly CLI'yı (veya Spectral'ı) çalıştırır ve Apidog'u tasarım, sahte sunucu (mocking), test yürütme ve yayınlanmış belgeler için kullanır. Terminaldeki açık kaynak kural setleriyle lintleme en iyi olduğu yerde lintleme yapın. Bir platformun en iyi olduğu yerde sahte sunucular kullanın, test yapın ve belgeleyin. Spesifikasyon aralarında akar: dosyayı CI'da lintleyin, aşağı yönlü her şey için Apidog'a aktarın.

Bu kombinasyon, birini diğerinin işini yapmaya zorlamak yerine her aracın gerçek gücünü kullanır.

SSS

Apidog CLI'da Redocly gibi özel kurallara sahip bir lint komutu var mı?

Hayır. Apidog, bir tanımın yapısını içe aktardığınızda doğrular, ancak apidog lint komutu ve CLI aracılığıyla özel stil rehberi kuralları yazmanın bir yolu yoktur. Yapılandırılabilir, kod öncelikli lintleme için Redocly CLI veya Spectral kullanın.

Redocly CLI, CI'da API testlerini çalıştırabilir mi?

Hayır. Redocly CLI lintleme, paketleme (bundle), bölme (split), birleştirme (join) ve belge oluşturma yapar. API testlerini yürütmez ve bir sahte sunucu barındırmaz. JUnit ve HTML raporlarıyla başsız test çalıştırmaları için apidog run kullanın.

Apidog, Redocly CLI gibi açık kaynak mı?

Hayır. Redocly CLI ve Spectral açık kaynaktır. Apidog freemium'dur: CLI, npm'den yüklenmesi ücretsizdir, ancak tamamen açık kaynak yazılım olarak değil, bir Apidog hesabı ve projesine karşı çalışır.

Doğrulama ve paketleme için swagger-cli kullanıyordum. Neye geçmeliyim?

Her iki araç da bunu kapsar. Redocly CLI, swagger-cli'nin adlandırılmış halefidir, redocly lint (düz doğrulama için spec kuralını yapılandırın) ve redocly bundle ile. Apidog, aynı alanı apidog import (doğrulama) ve apidog export (isteğe bağlı bir OpenAPI sürüm yükseltmesi ile paketleme) aracılığıyla kapsar ve aynı çalışma alanında sahte sunucu (mocking), test ve belgeler ekler.