DEV Community

Cover image for API Tasarımı için Ücretsiz Açık Kaynak CLI Araçları
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

API Tasarımı için Ücretsiz Açık Kaynak CLI Araçları

API tasarımı, kod göndermeden önce spesifikasyon dosyanızda başlar. Unutulan bir stil kuralı, gözden kaçan bozucu değişiklik veya önceki sürümden farklılaşan bir şema, üretimde düzeltildiğinde daha maliyetlidir. CLI araçları bu sorunları kaynakta yakalamanızı ve kontrolleri hem yerelde hem de CI işlem hattında aynı şekilde çalıştırmanızı sağlar. Daha geniş tasarım süreci için önce bir API nasıl tasarlanır rehberine bakabilirsiniz.

Apidog'u bugün deneyin

Bu yazıda açık kaynaklı API tasarım araç zincirinin pratik tarafına odaklanacağız. Listelenen araçlar izin verici lisanslarla kaynak kodu sunar, ücretsiz çalıştırılabilir, sürümleri sabitlenebilir ve kendi CI ortamınızda barındırılabilir. API sözleşmeniz bir Git deposunda yaşıyorsa, her geliştiricide ve her pipeline'da aynı kontrolleri çalıştırmak kritik önemdedir.

Her araç için kurulum komutu, hızlı doğrulama komutu ve kullanım senaryosu göreceksiniz:

  • Stil kuralları için linter'lar
  • Çok dosyalı spesifikasyonları paketleyen bir CLI
  • SDK, sunucu taslağı ve belge üreticisi
  • Sürümler arasındaki bozucu değişiklikleri tespit eden fark araçları

Hepsinin ortak dili OpenAPI Spesifikasyonu'dur. Bir araçla doğruladığınız OpenAPI dosyasını, sonraki araca doğrudan aktarabilirsiniz.

Not: Apidog bu araç zincirinde yer alabilir, ancak açık kaynak değildir. Ücretsiz katmanı olan ticari bir üründür ve aşağıdaki açık kaynaklı linter veya fark araçlarının yerine geçmez.

Bir CLI aracını API tasarımı için açık kaynak yapan nedir?

Bu listede bir aracın açık kaynaklı ve üretimde kullanılabilir sayılması için üç kriteri karşılaması gerekir:

  1. Açık lisans: MIT, Apache-2.0 veya benzeri bir lisansla yayınlanmalıdır. Böylece lisans veya koltuk maliyeti olmadan ticari projelerde kullanılabilir.
  2. Sürüm sabitleme ve bağımsız çalışma: Belirli bir sürüme sabitlenebilmeli, çevrimdışı veya hava boşluklu CI ortamlarında çalışabilmelidir.
  3. Bakım ve topluluk: Depoda güncel commit'ler, açık issue'lar, değişiklik günlüğü ve görünür bakım faaliyeti bulunmalıdır.

MIT lisanslı bir proje teknik olarak açık kaynak olabilir; ancak uzun süredir bakım almıyorsa üretim için risk oluşturur. Bu nedenle bakım durumu önemli olan yerlerde ayrıca belirtilmiştir.

Spectral: Esnek OpenAPI stil linter'ı

Stoplight tarafından geliştirilen Spectral, Apache-2.0 lisanslı bir API açıklaması linter'ıdır. OpenAPI 3.x, OpenAPI 2.0, AsyncAPI ve Arazzo belgelerinde YAML, JSON veya JavaScript tabanlı kural kümeleri çalıştırabilir.

Kurulum ve ilk kontrol:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral, varsayılan oas kurallarıyla eksik açıklamalar, geçersiz örnekler ve yapısal sorunlar gibi hataları tespit edebilir. Asıl fayda ise ekip standartlarınızı koda dönüştürmenizde ortaya çıkar.

Örneğin spectral.yaml dosyasıyla her endpoint için operationId zorunlu kılabilirsiniz:

extends:
  - spectral:oas

rules:
  operation-id-required:
    description: Her operasyon bir operationId içermelidir.
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
Enter fullscreen mode Exit fullscreen mode

Ardından bu kuralı CI veya yerel geliştirme ortamında çalıştırın:

spectral lint openapi.yaml --ruleset spectral.yaml
Enter fullscreen mode Exit fullscreen mode

En iyi kullanım alanı: API stil rehberini kod olarak uygulamak.

Sınırlama: Spectral tek bir spesifikasyonu kontrol eder. Eski ve yeni sürümleri karşılaştırarak bozucu değişiklik tespiti yapmaz. Bunun için oasdiff gibi bir araçla birlikte kullanın.

vacuum: Spectral kural kümeleriyle hızlı lint

Spectral standart araçsa, vacuum performans odaklı alternatiftir. MIT lisanslı bir Go linter'ıdır ve Spectral kural kümeleriyle uyumludur.

Kurulum ve lint:

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

-d bayrağı, ihlalleri kural bazında ayrıntılı gösterir. Mevcut Spectral kural dosyanızı doğrudan kullanabilirsiniz:

vacuum lint -d --ruleset spectral.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

vacuum ayrıca aynı spesifikasyondan HTML raporları ve dokümantasyon üretebilir. Tek derlenmiş ikili olarak çalıştığı için Node.js çalışma zamanı gerektirmez ve container tabanlı CI süreçlerine kolayca eklenir.

En iyi kullanım alanı: Büyük OpenAPI dosyalarını pre-commit hook veya hızlı CI döngülerinde kontrol etmek.

Sınırlama: Kural ekosistemi ve dokümantasyon büyük ölçüde Spectral modeline odaklanır. Genellikle kuralları Spectral formatında yazıp vacuum ile çalıştırırsınız.

Redocly CLI: Lint, doğrulama ve paketleme

Redocly CLI, MIT lisanslı bir OpenAPI CLI aracıdır. Lint işleminin yanında en önemli özelliği bundle komutudur.

Büyük API tanımlarını birden fazla dosyaya bölmek yaygın bir yaklaşımdır:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas.yaml
    └── responses.yaml
Enter fullscreen mode Exit fullscreen mode

Bu yapı Git farklarını okunabilir tutar ve birleştirme çakışmalarını azaltır. Bu yaklaşım, Git-native API tasarım iş akışının temel parçalarından biridir.

Kurulum, doğrulama ve tek dosyada paketleme:

npm install -g @redocly/cli

redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

bundle, $ref ile dağıtılmış kaynak dosyalarını tek bir OpenAPI belgesine dönüştürür. Bu çıktı; CI kontrolleri, mock sunucuları, belge siteleri veya kod üretim araçları için kullanılabilir.

En iyi kullanım alanı: Çok dosyalı OpenAPI projelerinde paketleme ve doğrulama.

Sınırlama: Varsayılan lint kuralları, kapsamlı bir özel Spectral kural kümesinden daha hafif olabilir. Yaygın yaklaşım; paketleme için Redocly CLI, detaylı stil kuralları için Spectral veya vacuum kullanmaktır.

openapi-generator: Tasarımı SDK'lara, taslaklara ve belgelere dönüştürün

openapi-generator, Apache-2.0 lisanslı bir kod üretim aracıdır. OpenAPI spesifikasyonundan birçok dil için istemci SDK'ları, sunucu taslakları ve dokümantasyon üretebilir.

Örneğin TypeScript Axios istemcisi üretmek için:

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Hedef üreticiyi -g bayrağıyla değiştirin:

# Go istemcisi
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Python istemcisi
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Java istemcisi
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım, API tasarım prensiplerinde ele alınan şema-öncelikli ve sözleşme odaklı geliştirme modelini destekler: Spesifikasyon doğruluk kaynağı olur, istemciler ve taslaklar bu sözleşmeden üretilir.

CI içinde şu akışı kullanabilirsiniz:

redocly bundle openapi.yaml -o dist/openapi.yaml
openapi-generator-cli generate -i dist/openapi.yaml -g typescript-axios -o ./client
git diff --exit-code ./client
Enter fullscreen mode Exit fullscreen mode

Bu kontrol, spesifikasyon değişmiş ancak üretilen istemci güncellenmemişse pipeline'ı başarısız yapar.

En iyi kullanım alanı: SDK, sunucu taslağı ve belge çıktısını API sözleşmesiyle senkron tutmak.

Sınırlama: JDK 11+ gerektirir. Üretilen kod çoğu zaman başlangıç noktasıdır ve hedef dile göre kalite değişebilir. Çıktıyı göndermeden önce inceleyin.

oasdiff: Bozucu değişiklikleri istemcilere ulaşmadan yakalayın

Linter, spesifikasyonunuzun kurallara uygun olduğunu söyler. Ancak örneğin bir alanı yeniden adlandırmanın mevcut istemcileri bozup bozmayacağını söylemez.

oasdiff, Apache-2.0 lisanslı bir Go aracıdır. Bir OpenAPI belgesinin iki sürümünü karşılaştırır ve özellikle bozucu değişiklikleri raporlar.

Kurulum ve bozucu değişiklik kontrolü:

go install github.com/oasdiff/oasdiff@latest

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Sık kullanılan komutlar:

# Yalnızca bozucu değişiklikleri gösterir
oasdiff breaking old-openapi.yaml new-openapi.yaml

# İnsan tarafından okunabilir değişiklik günlüğü üretir
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Tam farkı makine tarafından okunabilir biçimde verir
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Pull request kontrolü için örnek GitHub Actions adımı:

- name: Bozucu OpenAPI değişikliklerini kontrol et
  run: |
    oasdiff breaking \
      main-openapi.yaml \
      openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Bu sayede kaldırılan endpoint'ler, zorunlu hale gelen alanlar veya değişen yanıt şemaları üretime çıkmadan önce derlemeyi başarısız yapabilir.

En iyi kullanım alanı: Pull request ve release süreçlerinde bozucu değişiklikleri engellemek.

Sınırlama: Sadece spesifikasyonları karşılaştırır. OpenAPI dosyanız gerçek API davranışından gerideyse sonuçlar da sınırlı kalır. Stil kontrolü için Spectral veya vacuum ile birlikte kullanın.

Optic: Lint ve fark, ancak bakım uyarısıyla

Optic, MIT lisanslı bir araçtır. OpenAPI lint işlemini ve sürüm farkı kontrolünü tek CLI içinde birleştirir. Ayrıca gözlemlenen test trafiğinden spesifikasyon oluşturabilme yeteneği de sunar.

Kurulum ve fark kontrolü:

npm install -g @useoptic/optic

optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

Ancak burada önemli bir bakım uyarısı vardır: Optic'in halka açık deposu 2026 başlarında arşivlenmiştir ve proje aktif olarak sürdürülmemektedir. Kaynak kod hâlâ MIT lisanslıdır ve mevcut pipeline'larda çalışabilir; fakat yeni kurallar veya güvenlik güncellemeleri beklenmemelidir.

En iyi kullanım alanı: Zaten Optic kullanan ekipler veya tek CLI içinde lint ve fark kontrolü isteyen mevcut projeler.

Sınırlama: 2026 başı itibarıyla aktif bakım yoktur. Yeni projelerde bozucu değişiklik tespiti için oasdiff tercih edin ve Optic kullanılan sistemler için bir geçiş planı oluşturun.

Apidog'un nerede uyduğu ve uymadığı

Apidog açık kaynak değildir; OpenAPI lint işlemi yapmaz ve stil kurallarını uygulamaz. Bu görev için Spectral, vacuum veya Redocly CLI kullanmalısınız.

Apidog, farklı bir ihtiyaca odaklanır: Endpoint'leri ve veri şemalarını entegre bir ortamda tasarlamanıza, ardından sonucu OpenAPI olarak dışa aktarmanıza yardımcı olur. Dışa aktarılan OpenAPI dosyasını açık kaynaklı kontrol araç zincirine verebilirsiniz.

Örnek CLI akışı:

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Dışa aktarılan dosyayı ardından lint ve fark kontrollerine bağlayın:

spectral lint openapi.yaml --ruleset spectral.yaml
oasdiff breaking previous-openapi.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

CLI; endpoint, schema, mock ve import/export komut gruplarını içerir. Tüm komutlar için Apidog CLI kılavuzunun tamamına bakabilirsiniz.

Özetle Apidog, açık kaynaklı araç zinciriyle birlikte çalışabilen ticari ve entegre bir tasarım seçeneğidir. Linter'ın veya bozucu değişiklik kontrol aracının yerine geçmez.

Nasıl seçilir?

Araçları birbirinin alternatifi olarak değil, işlem hattının farklı aşamaları olarak düşünün. Çoğu ekip iki veya üç aracı birlikte kullanır.

Araç En iyi olduğu yer Yükleme Açık kaynak mı? Notlar
Spectral Stil rehberi linting'i npm i -g @stoplight/spectral-cli Evet (Apache-2.0) Referans linter; özel kurallar yazın
vacuum Büyük ölçekte hızlı linting brew install --cask daveshanley/vacuum/vacuum Evet (MIT) Spectral kural kümelerini Go hızında çalıştırır
Redocly CLI Paketleme + doğrulama npm i -g @redocly/cli Evet (MIT) Çok dosyalı $ref spesifikasyonları için idealdir
openapi-generator SDK / taslak / belge üretimi npm i -g @openapitools/openapi-generator-cli Evet (Apache-2.0) JDK 11+ gerektirir
oasdiff Bozucu değişiklik tespiti go install github.com/oasdiff/oasdiff@latest Evet (Apache-2.0) Aktif bakım var; PR kontrollerinde kullanın
Optic Tek araçta lint + fark npm i -g @useoptic/optic Evet (MIT) Depo 2026 başı itibarıyla arşivlendi
Apidog CLI Entegre tasarım + dışa aktarma npm i -g apidog-cli Hayır (ücretsiz katman) Linter değildir; OpenAPI dışa aktarır

Pratik bir başlangıç yığını:

# 1. Çok dosyalı OpenAPI tanımını paketle
redocly bundle openapi.yaml -o dist/openapi.yaml

# 2. Stil kurallarını kontrol et
spectral lint dist/openapi.yaml --ruleset spectral.yaml

# 3. Bozucu değişiklikleri kontrol et
oasdiff breaking previous-openapi.yaml dist/openapi.yaml

# 4. İstemci SDK'sını üret
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Bu araçları CI'a bağlayarak aşağıdaki kontrolleri otomatikleştirebilirsiniz:

  1. Spesifikasyon paketlenir.
  2. Stil ve yapısal kurallar doğrulanır.
  3. Eski sürüme göre bozucu değişiklikler kontrol edilir.
  4. İstemci SDK'ları ve belgeler üretilir.
  5. Üretilen çıktının depoyla senkron olduğu doğrulanır.

CLI dışındaki araçlara da bakmak isterseniz, API tasarımı ve testi için Swagger alternatifleri rehberini ve REST API'leri nasıl tasarlanır yazısını inceleyin.

Sonuç

Açık kaynaklı API tasarım CLI araç zinciri olgun ve ücretsizdir:

  • Spectral ve vacuum stil ve yapı kontrolleri yapar.
  • Redocly CLI çok dosyalı spesifikasyonları paketler.
  • openapi-generator istemciler, sunucu taslakları ve belgeler üretir.
  • oasdiff bozucu değişiklikleri pull request aşamasında yakalar.
  • Optic, aktif bakım almayan ancak mevcut pipeline'larda karşılaşabileceğiniz eski bir seçenektir.

Bu araçları CI'a bağladığınızda API sözleşmeniz her gönderimde otomatik olarak doğrulanır. Endpoint ve şema tasarımını entegre bir araçta yapıp temiz OpenAPI çıktısını aynı pipeline'a aktarmak isterseniz, Apidog'u indirin ve apidog-cli aracını deneyin.

Hedef değişmez: Tasarım sorunlarını kullanıcılarınıza ulaşmadan önce terminalde yakalayın.

Top comments (0)