DEV Community

Cover image for API İşbirliği İçin En İyi Hafif CLI Araçları
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

API İşbirliği İçin En İyi Hafif CLI Araçları

API işbirliği eskiden ağır bir uygulama açmak, senkronizasyonu beklemek ve ekip arkadaşınızın ne değiştirdiğini anlamak için paneller arasında gezinmek anlamına geliyordu. OpenAPI ile tanımlanmış bir API’de buna gerek yok: spesifikasyonu Git ile versiyonlayabilir, değişiklikleri terminalde inceleyebilir ve güvenli değişiklikleri CI üzerinden birleştirebilirsiniz.

Apidog'u bugün deneyin

Bu rehber, API işbirliğinin üç temel işini terminalden yapan hafif CLI araçlarını gösterir:

  1. Versiyonlama: Ekipte herkesin hangi OpenAPI sürümünü kullandığını takip etmek.
  2. İnceleme: Ne değiştiğini ve değişikliğin bozucu olup olmadığını görmek.
  3. Birleştirme ve paylaşım: Onaylanan değişikliği ortak doğruluk kaynağına eklemek.

Daha geniş bir araç seçimi için API işbirliği araçları derlememize bakabilirsiniz. Bu yazı, terminal öncelikli iş akışına odaklanır.

OpenAPI, bu araçların okuyup yazdığı resmi standarttır. Ortak diliniz openapi.yaml olduğunda, araçları Git kancalarına ve CI boru hatlarına kolayca bağlayabilirsiniz.

Bir CLI aracını API işbirliği için hafif yapan nedir?

Hafif bir CLI aracı genellikle şu özellikleri taşır:

  • Küçük kurulum: Tek bir ikili dosya, npx komutu veya npm install -g.
  • Hızlı çalışma: Komutu çalıştırır, sonucu üretir ve çıkar. Betikler ile Git kancaları için uygundur.
  • Az yapılandırma: Doğrudan bir OpenAPI dosyasına karşı çalışır.
  • Terminal önceliği: Çıktısı terminalde okunabilir ve CI sistemleri tarafından tüketilebilir.
  • Dar kapsam: Fark bulma, lintleme, yayınlama veya PR yönetimi gibi bir işi iyi yapar.

Aşağıdaki araçlar en odaklı seçeneklerden daha entegre akışlara doğru ilerler.

1. Git + spesifikasyon dosyası

En hafif araç zaten kullandığınız araçtır: Git.

openapi.yaml dosyanızı uygulama koduyla aynı depoda tutarsanız, geçmiş, inceleme ve değişiklik takibi varsayılan olarak gelir. Bir PR içinde dosya değişikliklerini görebilir, satır bazlı yorum yapabilir ve onay sonrası değişikliği birleştirebilirsiniz.

Bu yaklaşım, Git-yerel API işbirliğinin temelidir.

# Spesifikasyonu depoya ekleyin
git add openapi.yaml
git commit -m "Add pagination params to GET /orders"

# Ana dalla farkı inceleyin
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

En iyisi: Yeni araç kurmadan geçmiş ve kod incelemesi yapmak.

Sınırlama: YAML üzerinde ham Git diff çıktısı gürültülü olabilir. Anahtar sıralaması veya girintileme değişse bile API değişmiş gibi görünür. Bu nedenle Git’i anlamsal diff üreten araçlarla eşleştirmek iyi bir pratiktir.

2. oasdiff

oasdiff, iki OpenAPI spesifikasyonunu karşılaştıran tek bir Go ikili dosyasıdır. Değişikliklerin bozucu olup olmadığını belirler ve CI içinde birleştirme kapısı olarak kullanılabilir.

# macOS kurulumu
brew install oasdiff

# Yeni spesifikasyon mevcut istemcileri bozuyorsa komut başarısız olur
oasdiff breaking main-spec.yaml pr-spec.yaml

# exit 0 = güvenli
# exit 1 = bozucu değişiklik bulundu
Enter fullscreen mode Exit fullscreen mode

Tüm değişikliklerin okunabilir özetini almak için:

oasdiff changelog base.yaml revision.yaml
Enter fullscreen mode Exit fullscreen mode

CI iş akışına eklemek için örnek:

- name: Check breaking API changes
  run: oasdiff breaking main-spec.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

En iyisi: Bozucu API değişikliklerini merge öncesinde engellemek.

Sınırlama: Dokümantasyon yayınlamaz, dal veya PR yönetmez. Görevi spesifikasyon farklarını tespit etmektir.

3. Optic

Optic, OpenAPI değişikliklerini karşılaştırmak, lintlemek ve incelemek için npm ile kurulan bir CLI aracıdır. $ref, oneOf, allOf gibi karmaşık şema yapılarını anlayabilir.

# Kurulum
npm install -g @useoptic/optic

# Mevcut spesifikasyonu main dalındaki sürümle karşılaştırın
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

Bunu PR doğrulama adımı olarak kullanarak API düzeyindeki değişiklikleri görünür hale getirebilirsiniz.

En iyisi: PR içinde yapılandırılmış API değişikliği incelemesi yapmak.

Sınırlama: Node tabanlı olduğu için tek bir Go ikilisinden daha ağırdır. Kurallardan tam fayda sağlamak için yapılandırma ve denetim kurallarını benimsemeniz gerekir.

4. Bump.sh CLI

Bump.sh CLI, API belgelerini terminalden yayınlamanıza ve sürümler arasındaki farkları karşılaştırmanıza yardımcı olur.

Temel kullanım şu şekildedir:

# Kurulum
npm install -g bump-cli

# Paylaşılan API belgelerinin yeni sürümünü yayınlayın
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# Yerel dosya ile yayınlanan sürüm arasındaki farkı inceleyin
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

PR açıklamasına veya CI çıktısına değişiklik günlüğü eklemek için bump diff kullanabilirsiniz.

En iyisi: Ortak, güncel ve insan tarafından okunabilir API belgelerini spesifikasyonla senkron tutmak.

Sınırlama: Barındırılan belgeler ve dağıtım akışı ücretli bir Bump.sh ürününe bağlıdır. CLI istemcidir; ortak dokümantasyon yüzeyi platformlarında barındırılır.

5. Redocly CLI

Redocly CLI, OpenAPI spesifikasyonlarını lintlemek, paketlemek ve ortak kayıt defterine göndermek için kullanılabilir.

Özellikle çok dosyalı ve $ref kullanan API tanımlarında önce tek dosyalık bir yapıt üretmek faydalıdır:

# Kurulum gerektirmez; npx ile çalıştırın
npx @redocly/cli lint openapi.yaml

# Çok dosyalı spesifikasyonu tek dosyada paketleyin
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Paylaşılan kayıt defterine sürüm göndermek için:

# API anahtarı gerekir
npx @redocly/cli push openapi.yaml \
  --organization "Acme" \
  --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

En iyisi: Kurumsal stil kurallarına göre lintleme, çoklu dosya spesifikasyonlarını paketleme ve kanonik bir API kaynağı paylaşma.

Sınırlama: lint ve bundle yerelde çalışır; push ve kayıt defteri Redocly’nin barındırılan platformunun parçasıdır. Daha derin düzenleme iş akışları için işbirlikçi API spesifikasyon düzenleme rehberine bakın.

6. GitHub CLI (gh)

İnceleme süreciniz GitHub PR’larında ilerliyorsa, GitHub CLI tarayıcıya ihtiyaç duymadan PR oluşturmanızı, inceleyici istemenizi ve durumu kontrol etmenizi sağlar.

# Spesifikasyon değişikliği için PR oluşturun
gh pr create \
  --title "Add /orders pagination" \
  --body "Adds page + limit params"

# PR'ı onaylayın
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

Pratikte gh aracını oasdiff veya Optic ile birlikte kullanın:

  1. CLI ile PR oluşturun.
  2. CI’da anlamsal OpenAPI diff çalıştırın.
  3. Bozucu değişiklik varsa merge işlemini engelleyin.
  4. İnceleme tamamlandığında PR’ı birleştirin.

En iyisi: GitHub kullanan ekiplerde terminalden PR inceleme ve birleştirme akışını yürütmek.

Sınırlama: PR yönetir, API semantiğini analiz etmez. Bozucu değişiklik denetimi için oasdiff veya Optic eklemelisiniz.

7. Apidog CLI

Apidog CLI, tek amaçlı bir ikili yerine Apidog platformundaki tasarım, versiyonlama ve işbirliği verilerine terminalden erişen proje odaklı bir CLI aracıdır.

Kurulum:

npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

İşbirliği için üç komut grubu öne çıkar:

  • branch
  • merge-request
  • git-connection

İzole bir çalışma dalı oluşturmak için:

# Paylaşılan bir değişiklik için sprint dalı başlatın
apidog branch create \
  --type sprint \
  --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

--type bayrağı dal modelini belirler:

  • sprint: Belirli özellik veya sürüm çalışmaları için.
  • general: Sürekli geliştirme çalışmaları için.
  • ai: Bir aracının kaynak kodunu değiştirmeden kaynakları düzenlemesi için izole dal.

Değişiklik hazır olduğunda doğrudan ana dala birleştirmek yerine merge request oluşturun:

# Korunan main dalı için inceleme isteği oluşturun
apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

Spesifikasyonları Git deposunda yedeklemek ve geçmişini korumak için git-connection komutunu kullanabilirsiniz:

# Proje spesifikasyonlarını Git deposuna bağlama seçeneklerini inceleyin
apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

Apidog CLI, yapılandırılmış JSON çıktısında agentHints.nextSteps alanını da üretir. Bu, CLI’ın betiklerden veya yapay zeka aracılarından yönetilmesini kolaylaştırır.

Komutların tamamı için Apidog CLI tam kılavuzuna bakın.

En iyisi: Ayrı araçları bir araya getirmeden versiyonlama, inceleme ve birleştirme akışını tek CLI içinde yönetmek.

Sınırlama: Bu bir platform CLI’ıdır; çıplak bir yerel OpenAPI dosyası yerine Apidog projenizle çalışır. Ayrıca OpenAPI linter’ı değildir; stil kuralları için Redocly veya Spectral kullanın. Ekipte rol tabanlı erişim gerekiyorsa RBAC ile güvenli API işbirliği rehberini inceleyin.

Nasıl seçmeli?

Aracı, ekipte çözmek istediğiniz işbirliği problemine göre seçin.

Araç En iyi kullanım Kurulum Açık kaynak mı? Not
Git + spesifikasyon dosyası Geçmiş ve inceleme Zaten yüklü Evet (Git) YAML farkları gürültülü olabilir
oasdiff Bozucu değişiklik merge kapısı brew install oasdiff Evet (Apache 2.0) CI’da çıkış koduyla başarısız olur
Optic PR içinde yapılandırılmış inceleme npm i -g @useoptic/optic Evet (MIT) $ref, oneOf gibi yapıları anlar
Bump.sh CLI Dokümantasyon ve diff yayınlama npm i -g bump-cli CLI açık, barındırma ücretli Node 20+ gerekir
Redocly CLI Lintleme, paketleme, kayıt defterine gönderme npx @redocly/cli CLI açık, kayıt defteri ücretli push API anahtarı gerektirir
GitHub CLI Terminalden PR yönetimi brew install gh Evet (MIT) API semantiğini analiz etmez
Apidog CLI Entegre versiyonlama, inceleme ve birleştirme npm i -g apidog-cli Hayır, ücretsiz katman var branch, merge-request, git-connection

Çoğu ekip tek bir araçla sınırlı kalmaz. Pratik bir hafif yığın şu şekilde kurulabilir:

Git             → spesifikasyon geçmişi
oasdiff / Optic → anlamsal değişiklik ve bozucu değişiklik kontrolü
GitHub CLI      → PR oluşturma ve inceleme
Bump.sh / Redocly → dokümantasyon yayınlama
Enter fullscreen mode Exit fullscreen mode

Dallanma, inceleme ve birleştirmeyi tek CLI üzerinden yönetmek istiyorsanız Apidog bu üç alanı birlikte kapsar. Daha geniş seçenekler için API işbirliği ekip araçları karşılaştırmasına göz atın.

Sonuç

Terminalden API işbirliği üç adıma indirgenebilir:

  1. OpenAPI spesifikasyonunu versiyonlayın.
  2. Anlamsal farkı inceleyin.
  3. Onaylanan değişikliği ortak kaynağa birleştirin.

Git versiyonlama ve temel incelemeyi sağlar. oasdiff ve Optic, API değişikliklerinin anlamını ve bozucu etkisini kontrol eder. Bump.sh ile Redocly belgeleri yayınlar; GitHub CLI PR akışını yönetir. Apidog CLI ise versiyonlama, inceleme ve birleştirmeyi tek komut setinde bir araya getirir.

En hızlı başlangıç için spesifikasyonunuzu Git’e ekleyin, CI’da oasdiff breaking çalıştırın ve her API değişikliği için PR açın. Entegre bir akış istiyorsanız Apidog’u indirin, apidog-cli kurun ve terminalden ilk apidog branch create ile merge-request komutlarınızı çalıştırın.

Top comments (1)

Collapse
 
topstar_ai profile image
Luis •

Bu makaledeki API işbirliği için CLI araçlarına odaklanmanız gerçekten ilginç, özellikle de OpenAPI spesifikasyonunun entegrasyonu açısından. Benzer bir vấnteri çözmeye çalışırken, oasdiff gibi araçların bozucu değişiklikleri belirlemede ne kadar faydalı olabileceğini gördüm. Ancak,sometimes YAML dosyalarındaki küçük değişiklikler bile büyük sorunlara neden olabilir. Bu nedenle, CLI araçlarının yanı sıra, API istemci kodunun otomatik olarak üretilmesi ve test edilmesi için OpenAPI-generator gibi araçları da kullanıyorum. Bu araçlar API işbirliği sürecini daha da kolaylaştırabilir. Sizce, API işbirliği araçlarını seçerken nelere dikkat edilmeli ve hangilerinin daha geniş bir proje kapsamında kullanılması daha uygun olur?