Redocly CLI iyi bir araçtır. Eğer onu OpenAPI dosyalarını lint etmek, çoklu dosyalı bir spec’i tek bir dosyada birleştirmek veya Redoc belgelerini terminalden oluşturmak için kullandıysanız, bunu zaten biliyorsunuzdur. Peki neden Redocly CLI’a bir alternatif arayasınız ki?
Genellikle bu, araçların şekline bağlıdır. Redocly CLI odaklanmış, kod odaklı bir uzmandır: lint etme, birleştirme, bölme, birleştirme, belge oluşturma. Bu, bazı ekipler için tam olarak doğruyken, diğerleri için yeterli değildir. API'nizi tasarlayan, mock oluşturan ve test eden tek bir araç istiyorsanız, CLI böyle bir araç olmaya çalışmıyor ve olmamalı da.
Bu makale, barındırılan Redocly doküman ürününü değil, Redocly CLI'ı (açık kaynaklı @redocly/cli paketi) ele almaktadır. Barındırılan doküman platformunu veya Redoc'un kendisini karşılaştırıyorsanız, bunun yerine API dokümantasyonu için Redocly alternatifleri derlememizi okuyun. Bu yazı, redocly lint ve redocly bundle yazan ve iş akışlarına başka nelerin uyduğunu bilmek isteyen kişiler içindir.
Redocly CLI Gerçekten Ne İyi Yapar?
Redocly CLI açık kaynaklı ve terminal tabanlıdır. Bir kez kurarsınız ve işlerini düzgün bir şekilde yapan sıkı bir komut setine sahip olursunuz. Redocly CLI belgeleri hepsini kapsar, ancak işte kısa versiyonu.
Lint etmek, imzası niteliğindeki gücüdür. redocly lint, OpenAPI, AsyncAPI, Arazzo veya Open-RPC açıklamanızı doğrular ve ardından üzerine stil rehberi kurallarını uygular. Her şeyi bir redocly.yaml dosyası aracılığıyla yapılandırırsınız: yerleşik bir kural kümesi (minimal, recommended, recommended-strict veya spec) seçebilir veya kendi özel kurallarınızı yazabilirsiniz. Birçok ekip arasında CI'da tutarlı API tasarımının uygulanmasını istiyorsanız, yapılandırma odaklı bu yönetimi geçmek zordur.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
Bundle, split ve join, spec'in iç işleyişini yönetir. redocly bundle, $ref işaretçilerini takip eder ve tek bir birleştirilmiş dosya üretir. redocly split bunun tersini yapar, tek bir açıklamayı çoklu dosya düzenine ayırır. redocly join (deneysel), birden fazla OpenAPI dosyasını tek bir dosyada birleştirir.
redocly bundle openapi.yaml --output dist/openapi.json
Belgeler build-docs komutundan gelir. Bu komut, bağımsız bir Redoc HTML sayfası üretir ve preview-docs size canlı yerel bir önizleme sunar.
redocly build-docs openapi.yaml -o docs.html
Yani ihtiyaçlarınız "stil rehberine göre doğrula, spec'i birleştir ve Redoc belgelerini yayınla, hepsi terminalden" ise, Redocly CLI güçlü bir varsayılan seçenektir. Birçok ekip onu kullanmaya devam etmelidir. Başka bir araca bakma nedenleri kapsamla ilgilidir, kaliteyle değil.
Neden İnsanlar Bir Alternatif Arıyor?
Birkaç tekrar eden durum var:
- Yalnızca lint ve dokümanların ötesinde hepsi bir arada bir platform istiyorsunuz. Redocly CLI API testlerini çalıştırmaz ve bir mock sunucusu barındırmaz. Eğer tasarım, mock ve bir test çalıştırıcısına da ihtiyacınız varsa, etrafında bir araç zinciri oluşturuyorsunuz demektir.
- CLI'nın yanı sıra bir GUI istiyorsunuz. Redocly, tasarımsal olarak kod odaklıdır. Eğer ekibinizde görsel olarak çalışmayı tercih eden insanlar varsa, sadece terminal tabanlı yönetim zor satılabilir.
- CI için yerleşik bir test çalıştırıcısı istiyorsunuz. Linting, spec sorunlarını yakalar. Çalışan API'nin nasıl davrandığını size söylemez. Bu ayrı bir araçtır.
- Beş aracı bir araya getirmek istemiyorsunuz. Lint için Spectral, paketleme ve belgeler için Redocly, testler için Postman veya Newman, mocklar için başka bir şey. Bu çalışır, ancak bakımı gereken çok hareketli parça var.
Bu noktaların her biri farklı bir alternatife işaret ediyor. Onları eşleştirelim.
Gerçekten İstediğinize Göre Kısa Liste
Apidog, tüm API yaşam döngüsü için tek bir platform istiyorsanız
Apidog, hepsi bir arada bir API platformudur: tasarım, mock, test ve dokümantasyon tek bir yerde, içe ve dışa aktarım ile CI test çalıştırmaları için bir CLI ile. Bir linter'ı, bir paketleyiciyi, bir test çalıştırıcısını ve bir mock sunucusunu bir araya getirmek yerine, tüm yaşam döngüsü için tek bir araca sahip olmayı tercih ettiğinizde doğru seçimdir.
İşte dürüst kısım. Apidog, Redocly'nin lint'i gibi yapılandırılabilir, kod odaklı, özel kural kümeleriyle stil rehberi linter'ına sahip değildir. Ne apidog lint komutu vardır ne de CLI aracılığıyla Spectral veya Redocly tarzı özel kurallar yazmanın bir yolu. Apidog, bir spec'i içe aktardığınızda yapıyı doğrular, ancak katı, özelleştirilebilir tasarım yönetimi sizin için önemli olan tek şeyse, Apidog tek başına redocly lint'in yerini alamaz. Bu iş için Spectral ile eşleştirin. Buna geri döneceğiz.
Apidog'un Redocly CLI'da olmayanları şunlardır: görsel bir tasarımcı, yerleşik bir mock sunucusu, görsel bir test oluşturucu ve bir CI test çalıştırıcısı. CLI, terminalde olması gereken kısımları yönetir.
# Kurulum ve kimlik doğrulama (uygulamadan token: avatar > Hesap Ayarları > API Erişim Token'ı)
npm install -g apidog-cli@latest
apidog login --with-token <TOKEN_INIZ>
# Bir spec'i bir projeye aktarma (çoklu dosyalı $ref'leri doğrular + çözer)
apidog import --project 123456 --format openapi --file ./openapi.json
# Tek bir birleştirilmiş dosyayı dışa aktarma ve OpenAPI sürümünüzü seçme
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# CI'da birden çok rapor formatıyla bir test senaryosu çalıştırma
apidog run --project 123456 -t <testSenaryoId> -e <ortamId> -r "cli,html,json,junit"
apidog import, alım sırasında doğrulama işini yapar ve apidog export, dışa aktarım sırasında paketleme işini yapar (tek bir dosya çıkarır ve OAS sürümünü yükseltebilir). Tüm komut listesi Apidog CLI belgelerinde bulunur ve Apidog CLI eksiksiz rehberimiz her bayrağı ayrıntılı olarak açıklar. En iyisi: tasarım, mock, test ve belgeleri tek bir çatı altında isteyen ekipler için.
Redocly'den tek istediğiniz linter ise Spectral
Eğer uzandığınız tek şey redocly lint ise, platform değiştirmenize gerek yoktur. Stoplight'ın Spectral'ı, Redocly'nin linting'iyle en doğrudan örtüşen açık kaynaklı, kural tabanlı linter'dır. Kuralları YAML olarak yazar, bunları herhangi bir OpenAPI veya AsyncAPI belgesine karşı çalıştırır ve CI'ya bağlarsınız.
Spectral ve Redocly'nin linter'ı yakın akrabalardır. Her ikisi de yapılandırma odaklıdır, her ikisi de kural kümeleri sunar, her ikisi de özel kurallar yazmanıza olanak tanır. Aralarındaki seçim genellikle ekosistem uyumu ve ekibinizin hangi kural kümesi formatını zaten bildiğine bağlıdır. Spectral OpenAPI linting üzerine derinlemesine incelememiz kural yazımını kapsar ve tam bir resim istiyorsanız daha geniş API linting rehberi linting ortamını karşılaştırır. En iyisi: asıl ihtiyacı saf, özelleştirilebilir spec linting olan ekipler için.
Çoğunlukla belgeler istiyorsanız Scalar veya Bump.sh
Redocly CLI'nın önemsediğiniz kısmı build-docs ise, alternatif bir dokümantasyon aracıdır, bir platform değil. Scalar ve Bump.sh her ikisi de bir OpenAPI açıklamasını kendi görünüm ve özellik setleriyle barındırılan, gezilebilir referans belgelere dönüştürür. Linting veya test etme yerine belge deneyimine odaklanırlar. En iyisi: birincil amacı iyi görünen, sürdürülebilir API referans belgeleri olan ekipler için.
Artık pek bir seçenek olmayan swagger-cli
Swagger-cli'yi hala eski rehberlerde göreceksiniz, bu yüzden net olmakta fayda var: swagger-cli kullanımdan kaldırılmıştır. swagger-cli GitHub deposu artık bakımının yapılmadığını ve kullanıcıları halefi olarak Redocly CLI'a yönlendirdiğini belirtiyor.
Sadece iki komutu vardı: swagger-cli validate ve swagger-cli bundle. Stil kurallarıyla hiç lint etmedi, belge oluşturmadı, test çalıştırmadı ve hiçbir şeyi mock etmedi. Eğer bugün onu kullanıyorsanız, ondan uzaklaşmalısınız, ona geçmemelisiniz. Swagger-cli nasıl kullanılır rehberimiz ne yaptığını kapsar ve Redocly bile tam bayrak eşleştirmesiyle swagger-cli'dan geçiş rehberi yayınlar. Eksiksiz olması için bu eşleştirmeyi aşağıda vereceğiz.
Karşılaştırma Tablosu
İşte seçeneklerin Redocly CLI'ın üstlendiği görevlere göre nasıl sıralandığı. "Özel kuralları lint et" terimi, özel kural kümeleriyle yapılandırılabilir, kod odaklı bir stil rehberi linter'ını ifade eder.
| Araç | Özel kuralları lint et | Paketle | Belgeler | Mock | Test | GUI | Açık kaynak | En iyisi |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Evet | Evet | Evet (Redoc) | Hayır | Hayır | Hayır | Evet | Terminalden kod odaklı lint, paketleme ve belge yönetimi |
| Apidog | Hayır | Dışa aktarım yoluyla | Evet | Evet | Evet (CI çalıştırıcısı) | Evet | Hayır (freemium) | Tasarım, mock, test ve belgeler için tek platform |
| Spectral | Evet | Hayır | Hayır | Hayır | Hayır | Hayır | Evet | Saf, özelleştirilebilir OpenAPI/AsyncAPI linting |
| Scalar / Bump.sh | Hayır | Hayır | Evet | Hayır | Hayır | Evet | Değişir | Barındırılan API referans belgeleri |
| swagger-cli | Hayır | Evet | Hayır | Hayır | Hayır | Hayır | Evet (kullanımdan kaldırıldı) | Yeni bir şey yok, bakımı yapılmıyor |
Tabloya bir not: Apidog'un "Dışa aktarım yoluyla" ifadesi, apidog export'un tek bir birleştirilmiş dosya çıkardığı anlamına gelir ki bu, redocly bundle'ı çalıştırmanın pratik nedenini karşılar, ancak birebir bir bundle komutu değildir. Ve Apidog, açık kaynak değil, freemium'dur; Redocly CLI ve Spectral ise her ikisi de açık kaynaktır. Bu ödünleşmeleri olduğu gibi kabul edin.
Swagger-cli'dan Redocly CLI paketleme bayrak eşleştirmesi
Eğer kullanımdan kaldırılmış swagger-cli kullanıyorsanız ve Redocly paketleme için hedefinizse, bayraklar düzgün bir şekilde eşleşir:
| swagger-cli | Redocly CLI | Anlamı |
|---|---|---|
-o, --outfile <dosya> |
--output (veya -o) |
Çıktı yerine bir dosyaya yaz |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
Çıktı dosyası türü |
-r, --dereference |
-d, --dereferenced |
Tüm $ref'leri tamamen satır içine al |
Yani swagger-cli bundle -o output.json, redocly bundle --output output.json haline gelir.
Net Bir Öneri
Tek bir kazanan yok, çünkü doğru cevap, Redocly CLI'ın hangi işini değiştirmeye çalıştığınıza bağlıdır.
Yönetimi tam olarak ihtiyacınız olan şeyse Redocly CLI'ı kullanmaya devam edin. Tamamen terminalden çalıştırdığınız hafif, açık kaynaklı, yapılandırma odaklı bir linter, paketleyici ve Redoc belge oluşturucu gerçekten iyi bir kurulumdur. Burada, uygun bir aracı terk etmek için bir neden yoktur.
Bir araç zinciri oluşturmaktan sıkıldıysanız ve tasarım, mock, test ve belgeleri terminale uygun kısımlar için CLI ile tek bir platformda istiyorsanız Apidog'u seçin. Her aşama için ayrı araçları sürdürmeyi bırakır ve ekibinizdeki görsel arayüz isteyen insanlar için bir GUI edinirsiniz. Yalnızca özel kural linting'e de ihtiyacınız varsa Spectral ile eşleştireceğiniz konusunda gerçekçi olun. CI/CD işlem hattındaki Apidog CLI rehberi, test çalıştırıcısının bir işlem hattına nasıl yerleştiğini gösterir ve Apidog CLI ve Newman karşılaştırması, onu birçok ekibin zaten kullandığı çalıştırıcıyla karşılaştırır. Apidog'u indirebilir ve kredi kartı gerektirmeden ücretsiz deneyebilirsiniz.
Tüm mesele linting ise Spectral'ı seçin. Tek bir komutu değiştirmek için platform değiştirmeyin.
Dürüst bir çerçeve: Redocly kod odaklı bir CLI uzmanıdır ve Apidog hepsi bir arada görsel bir platformdur. Farklı paradigmalar, birebir bir değişim değil. Uygun olana göre seçin.
Sıkça Sorulan Sorular
Apidog, Redocly CLI için birebir bir yedek midir? Hayır, ve bunu baştan dürüstçe söylemek daha iyidir. Apidog yaşam döngüsünün daha fazlasını kapsar (tasarım, mock, test, belgeler) ancak redocly lint gibi özel kural kümeli bir linter'a sahip değildir. Eğer katı, yapılandırılabilir spec yönetimi asıl işinizse, Redocly'nin linter'ını kullanmaya devam edin veya Spectral'ı kullanın. Apidog, birkaç araç yerine tüm API yaşam döngüsü için tek bir araç istediğinizde tercih edilir.
Apidog CLI'da lint komutu var mı? Hayır. Apidog, bir spec'i apidog import ile içe aktardığınızda yapıyı doğrular, ancak ne apidog lint komutu vardır ne de CLI aracılığıyla Spectral veya Redocly tarzı özel kurallar yazmanın bir yolu. Bunun için Apidog'u Spectral ile eşleştirin.
Redocly CLI olmadan bir OpenAPI dosyasını paketleyebilir miyim? Evet. apidog export --project <id> --format openapi --output ./openapi.json tek bir birleştirilmiş dosya çıkarır ve --oas-version ile belirli bir OpenAPI sürümünü hedefleyebilir. Bu, kelimesi kelimesine bir bundle komutu değildir, ancak aynı pratik ihtiyacı karşılar. Eğer sadece paketleme istiyorsanız ve başka bir şey istemiyorsanız, redocly bundle hala iyi, odaklanmış bir seçimdir.
2026'da swagger-cli kullanmalı mıyım? Hayır. swagger-cli kullanımdan kaldırılmıştır ve bakımı yapılmamaktadır, kendi deposu halefi olarak Redocly CLI'ı işaret etmektedir. Sadece doğrulamayı ve paketlemeyi yapmıştır. Bu iş için Redocly CLI'ı kullanın veya yaşam döngüsünün geri kalanını da istiyorsanız Apidog gibi bir platforma geçin.
Bununla Redocly belge platformu karşılaştırması arasındaki fark nedir? Bu yazı, açık kaynaklı @redocly/cli aracı hakkındadır: lint, paketle, böl, birleştir ve belge oluştur. Eğer barındırılan Redocly belge ürününü veya Redoc'u bir dokümantasyon oluşturucu olarak karşılaştırıyorsanız, bunun yerine API dokümantasyonu için Redocly alternatifleri yazımızı okuyun. Bu ikisi, tesadüfen aynı adı paylaşan farklı ürünleri kapsar. Spec'in kendisi için OpenAPI Spesifikasyonu doğruluk kaynağıdır ve npm üzerindeki Redocly CLI güncel kurulum detaylarını bulabileceğiniz yerdir.