DEV Community

Cover image for API Tasarımı İçin En İyi Hafif CLI Araçları
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

API Tasarımı İçin En İyi Hafif CLI Araçları

Çoğu API tasarım aracı, basit bir kontrol için bile gereğinden fazla kurulum ister. Oysa adlandırma kuralını doğrulamak, bölünmüş bir OpenAPI spesifikasyonunu birleştirmek veya istemcileri bozacak alan değişikliklerini yakalamak için terminalden çalışan tek amaçlı CLI araçları yeterlidir.

Apidog'u bugün deneyin

Bu yazıda, API tasarım iş akışına doğrudan ekleyebileceğiniz altı hafif aracı uygulamalı olarak ele alacağız. Her araç için kurulum komutunu, temel kullanım örneğini ve CI içinde nerede kullanılacağını göreceksiniz. Araçların ortak dili OpenAPI Spesifikasyonu'dur; dolayısıyla bir aracın çıktısını diğerine aktarabilirsiniz.

API tasarım sürecinin tamamını görmek için önce API nasıl tasarlanır kılavuzuna göz atabilirsiniz.

Bir CLI aracını API tasarımı için hafif yapan nedir?

Bir CLI aracının hafif olması, özellik sayısından çok kurulum ve kullanım sürtünmesiyle ilgilidir. Pratikte üç kriter önemlidir:

  1. Hızlı kurulum: Tek ikili dosya veya npx ile çalışabilmelidir.
  2. Az yapılandırma: İlk sonucu almak için uzun bir config dosyası gerektirmemelidir.
  3. Betiklenebilir çıktı: CI'da çalışmalı, anlamlı çıkış kodları üretmeli ve GUI gerektirmemelidir.

Aşağıdaki araçlar, en hızlı benimsenebilecek seçeneklerden daha kapsamlı olanlara doğru sıralanmıştır.

1. Redocly CLI: Kurulumsuz lint ve paketleme

Redocly CLI, OpenAPI dosyalarını doğrulamak ve çoklu dosya yapısını tek bir dosyada birleştirmek için pratik bir seçenektir. Global kurulum yapmadan npx ile çalıştırabilirsiniz.

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ne zaman kullanılır?

Özellikle $ref kullanarak bölünmüş büyük spesifikasyonlarda bundle komutu faydalıdır.

Örnek proje yapısı:

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

CI veya dokümantasyon üretiminden önce dosyaları tek bir spesifikasyonda birleştirin:

npx @redocly/cli@latest bundle openapi/openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım kaynak dosyalarını küçük ve okunabilir tutar. Git farkları daha anlamlı olur ve birleştirme çakışmaları azalır. Bu yapı, Git-tabanlı API tasarım iş akışının temel parçalarından biridir.

En iyi kullanım: Çoklu dosya OpenAPI spesifikasyonlarını paketlemek ve hızlı lint çalıştırmak.

Sınırlama: Varsayılan lint kuralları temel kontroller sağlar. Daha katı ekip kuralları için Spectral ekleyin.

2. Spectral: API stil kılavuzunu kod olarak uygulayın

Stoplight Spectral, OpenAPI, AsyncAPI ve Arazzo belgeleri için açık kaynaklı bir linter'dır. Varsayılan kurallarla başlayabilir, ardından ekibinizin API standartlarını YAML, JSON veya JavaScript kural seti olarak tanımlayabilirsiniz.

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

İlk çalıştırmada yerleşik oas kuralları; eksik açıklamalar, geçersiz örnekler ve yapısal hatalar gibi sorunları tespit eder.

Özel kural ekleme

Proje köküne .spectral.yaml dosyası ekleyin:

extends:
  - spectral:oas

rules:
  operation-id-required:
    description: Her işlem operationId içermelidir.
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  kebab-case-paths:
    description: URL yolları kebab-case olmalıdır.
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: ^(/[a-z0-9]+(-[a-z0-9]+)*)+$
Enter fullscreen mode Exit fullscreen mode

Ardından lint işlemini tekrar çalıştırın:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Bu yöntemle operationId, hata şeması, endpoint adlandırması veya açıklama zorunluluğu gibi standartları CI içinde zorunlu hale getirebilirsiniz. Böylece API tasarım ilkelerini doğrudan doğrulanabilir kurallara dönüştürürsünüz.

En iyi kullanım: Ekip API stil kılavuzunu kod olarak uygulamak.

Sınırlama: İki API sürümünü karşılaştırmaz; önemli değişiklikler için oasdiff kullanın.

3. oasdiff: Önemli değişiklikleri CI'da engelleyin

Bir linter spesifikasyonun geçerli olup olmadığını söyler. Ancak bir alanı kaldırmanın veya zorunlu hale getirmenin mevcut istemcileri bozup bozmayacağını göstermez.

oasdiff, iki OpenAPI sürümünü karşılaştırır ve istemcileri bozabilecek değişiklikleri tespit eder. Tek bir Go ikilisi olarak çalışır ve ek çalışma zamanı gerektirmez.

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 önemli değişiklikleri listele
oasdiff breaking old-openapi.yaml new-openapi.yaml

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

# Tam fark çıktısını al
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

GitHub Actions örneği 

name: OpenAPI Breaking Changes

on:
  pull_request:

jobs:
  breaking-changes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install oasdiff
        run: go install github.com/oasdiff/oasdiff@latest

      - name: Check breaking changes
        run: |
          oasdiff breaking \
            api/openapi-main.yaml \
            api/openapi-pr.yaml
Enter fullscreen mode Exit fullscreen mode

Bu kontrol sayesinde örneğin zorunlu bir alanın kaldırılması, endpoint'in silinmesi veya parametre tipinin değiştirilmesi üretime ulaşmadan önce pull request aşamasında yakalanabilir.

En iyi kullanım: CI'da önemli değişiklikleri engellemek.

Sınırlama: Yalnızca spesifikasyonları karşılaştırır; gerçek API davranışı ile OpenAPI dosyanızın senkron kalması gerekir.

4. Optic: Tek CLI'da lint ve fark

Optic, OpenAPI lint işlemi ile sürüm farkı kontrolünü tek araçta birleştirir.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

Bu yaklaşım, özellikle mevcut işlem hattında zaten Optic kullanan ekipler için faydalı olabilir.

Ancak önemli bir durum var: Optic'in herkese açık deposu Ocak 2026'da arşivlendi ve proje artık sürdürülmüyor. Kaynak kodu hâlâ kullanılabilir olsa da yeni özellikler veya güvenlik güncellemeleri beklememelisiniz.

Yeni projelerde önemli değişiklik tespiti için oasdiff, stil kuralları için ise Spectral veya Redocly tercih edin.

En iyi kullanım: Zaten Optic kullanan mevcut projeler.

Sınırlama: 2026 başı itibarıyla sürdürülmüyor; geçiş planı hazırlayın.

5. openapi-generator: Spesifikasyondan SDK ve sunucu taslağı üretin

openapi-generator, OpenAPI spesifikasyonundan istemci SDK'ları, sunucu taslakları ve dokümantasyon üretir. JVM gerektirdiği için listedeki en ağır araçtır, ancak sözleşmeden kod üretmek için güçlü bir seçenektir.

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

Üretici değiştirerek farklı hedefler için kod oluşturabilirsiniz:

# 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

CI içinde kullanın

Spesifikasyon değiştiğinde oluşturulan istemciyi yeniden üretin:

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

Bu yaklaşım, istemci kütüphanesinin API sözleşmesinden sapmasını önler ve tasarım öncelikli API geliştirmenin temel iş akışlarından biridir.

En iyi kullanım: SDK, sunucu taslağı ve belge üretimi.

Sınırlama: JDK 11 veya üzeri gerekir. Oluşturulan kod genellikle özelleştireceğiniz bir başlangıç noktasıdır.

6. Apidog CLI: Terminalden endpoint ve şema tasarlayın

Yukarıdaki araçlar, mevcut OpenAPI spesifikasyonunu doğrular, karşılaştırır veya dönüştürür. Apidog ise bir önceki adımı kapsar: endpoint'leri ve veri şemalarını komut satırından tasarlamak.

npm install -g apidog-cli

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

CLI üzerinden aşağıdaki kaynaklarla çalışabilirsiniz:

  • endpoint
  • schema
  • security-scheme
  • folder
  • mock
  • import
  • export

Örneğin, tasarım çalışmasını tamamladıktan sonra OpenAPI çıktısını dışa aktarın:

apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ardından bu dosyayı diğer araçlara aktarın:

spectral lint openapi.yaml

npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

oasdiff breaking previous-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog CLI çıktısı agentHints.nextSteps içeren yapılandırılmış JSON olarak gelir; bu sayede çıktıyı otomasyon adımlarında kullanabilirsiniz. Tüm komutlar için eksiksiz Apidog CLI kılavuzuna bakın.

Apidog bir linter değildir ve stil kurallarını uygulamaz. Bu görev Spectral veya Redocly'ye aittir. Ayrıca açık kaynak değildir; ücretsiz katmanı olan ticari bir üründür.

En iyi kullanım: Endpoint ve şemaları tasarlamak, ardından OpenAPI olarak dışa aktarmak.

Sınırlama: Lint aracı değildir; doğrulama ve önemli değişiklik kontrolleri için diğer CLI'larla birlikte kullanılmalıdır.

Nasıl seçilir?

Çoğu ekip tek bir araç seçmek yerine araçları iş akışına göre birleştirir.

Araç En iyi olduğu alan Kurulum Açık kaynak mı? Notlar
Redocly CLI Paketleme ve hızlı lint npx @redocly/cli@latest Evet, MIT Çoklu dosya spesifikasyonları için uygun
Spectral Stil kılavuzu linting npm i -g @stoplight/spectral-cli Evet, Apache-2.0 Özel kurallar yazılabilir
oasdiff Önemli değişiklik tespiti go install github.com/oasdiff/oasdiff@latest Evet, Apache-2.0 Tek Go ikilisi, sürdürülüyor
Optic Tek CLI'da lint ve fark npm i -g @useoptic/optic Evet, MIT Deposu Ocak 2026'da arşivlendi
openapi-generator SDK, taslak ve belge üretimi npm i -g @openapitools/openapi-generator-cli Evet, Apache-2.0 JDK 11+ gerekir
Apidog CLI Endpoint tasarımı ve OpenAPI dışa aktarma npm i -g apidog-cli Hayır, ücretsiz katman Linter değildir

Önerilen hafif API araç zinciri

Pratik bir pipeline şu şekilde kurulabilir:

# 1. Endpoint ve şemaları tasarla, OpenAPI'yi dışa aktar
apidog export --format openapi -o openapi.yaml

# 2. Stil ve yapı kurallarını doğrula
spectral lint openapi.yaml

# 3. Çoklu dosya yapısını tek dosyada paketle
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. Önceki sürüme göre önemli değişiklikleri engelle
oasdiff breaking previous-openapi.yaml dist/openapi.yaml

# 5. Gerekirse SDK üret
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Bu akışta her araç tek bir sorumluluğa odaklanır:

  • Apidog CLI: Tasarım ve dışa aktarma
  • Spectral: Stil kuralları
  • Redocly CLI: Paketleme ve hızlı doğrulama
  • oasdiff: Geriye dönük uyumluluk kontrolü
  • openapi-generator: SDK ve taslak üretimi

Daha geniş araç seçenekleri için API tasarımı ve testi için Swagger alternatifleri rehberine, REST tasarım temelleri için de REST API'leri nasıl tasarlanır yazısına bakabilirsiniz.

Özet

Hafif bir API tasarım araç zinciri, OpenAPI dosyanızı küçük komutlarla doğrulamanızı, paketlemenizi, karşılaştırmanızı ve kod üretmenizi sağlar:

  • Redocly CLI: Hızlı lint ve paketleme
  • Spectral: Stil kılavuzunu zorunlu kılma
  • oasdiff: Önemli değişiklikleri engelleme
  • openapi-generator: İstemci ve sunucu kodu üretme
  • Optic: Mevcut projelerde karşılaşabileceğiniz, ancak artık sürdürülmeyen seçenek
  • Apidog CLI: Endpoint ve şema tasarlayıp OpenAPI dışa aktarma

Endpoint ve şemaları tek yerde tasarlayıp OpenAPI tabanlı işlem hattına aktarmak için Apidog'u indirin ve apidog-cli ile başlayın.

Top comments (0)