Git ile Çalışan En İyi API Araçları

Kodunuz Git'te yaşar; API spesifikasyonlarınız, istek koleksiyonlarınız, belgeleriniz ve testleriniz çoğu zaman yaşamaz. Sonuç: GUI veya satıcı bulutunda duran API varlıkları koddan ayrılır, PR'lar eksik incelenir, dokümanlar eskir ve “benim makinemde çalışıyor” tipi API hataları üretime taşınır.

Apidog'u bugün deneyin

Çözüm, API varlıklarını da kod gibi yönetmektir: dosya olarak saklayın, çekme isteklerinde inceleyin, her özellik için dallandırın ve CI ile her gönderimde doğrulayın. Modern API araçları artık düz metin dosyaları okuyup yazabiliyor, GitHub veya GitLab ile senkronize olabiliyor ve ekibinizin mevcut review akışına uyabiliyor.

Bu kılavuz, 2026'da Git ile çalışan API araçlarını uygulama perspektifiyle gruplandırır: hepsi bir arada platformlar, istemciler, tasarım/spesifikasyon araçları, dokümantasyon ve CI testleri. Önce Apidog ile başlayacağız; ardından ekibiniz için sürüm kontrollü bir API yığını nasıl kuracağınızı adım adım ele alacağız. Spesifikasyonlarınızı depoya taşımaya başladıysanız, Git-yerel API iş akışı kılavuzu bu yazıyla birlikte okunabilir.

TL;DR: Git dostu API araçları

Kısa liste:

• Apidog: Tasarım, test, dokümantasyon ve mock sunucuları tek bir OpenAPI kaynağına bağlamak isteyen ekipler için hepsi bir arada seçenek.
• Bruno ve Insomnia: API isteklerini dosya olarak saklamak ve Git ile takip etmek isteyen geliştiriciler için güçlü istemciler.
• Stoplight ve Redocly: OpenAPI tasarımı, linting ve spesifikasyon yönetimi için Git destekli araçlar.
• Mintlify, Fern ve ReadMe: Depodan yayınlanan kod olarak dokümantasyon akışları için.
• Newman, Step CI ve Schemathesis: API testlerini CI içinde çalıştırmak için.

Temel seçim kriteri basit: API varlıklarını yalnızca satıcı veritabanında değil, commit edilebilir dosyalar olarak saklayan araçları tercih edin.

API iş akışınız neden Git'te olmalı?

API spesifikasyonlarını ve testlerini Git'e almak sadece düzen meselesi değildir. Doğrudan hata önleme ve ekip içi görünürlük sağlar.

1. Tek doğruluk kaynağı oluşturursunuz

Spesifikasyon, testler ve belgeler kodla aynı depoda yaşadığında ikinci bir sistem senkronize etmek zorunda kalmazsınız.

Örnek repo yapısı:

repo/
  src/
  api/
    openapi.yaml
    tests/
      contract-tests.yaml
    docs/
      overview.md

Bir endpoint değiştiğinde aynı PR içinde şunlar birlikte güncellenir:

src/orders/controller.ts
api/openapi.yaml
api/tests/orders.yaml
api/docs/orders.md

2. API sözleşmesi review edilebilir hale gelir

Bir API sözleşmesi değişikliği, kod değişikliği kadar risklidir. Dosya olarak tutulduğunda ekip arkadaşınız satır satır yorum yapabilir.

Bu yaklaşım, kod olarak spesifikasyon modelinin temelidir.

3. Her özellik için dal açabilirsiniz

Yeni bir endpoint veya breaking change için ayrı dal kullanabilirsiniz:

git checkout -b feature/order-status

Sonra kod, OpenAPI tanımı, test ve doküman değişikliklerini aynı PR içinde birleştirirsiniz.

4. CI ile otomatik doğrulama yapabilirsiniz

OpenAPI dosyanız depodaysa her push'ta lint, validation ve contract test çalıştırabilirsiniz. Bu, bozuk sözleşmeleri üretime gitmeden yakalar. Hassas API dokümantasyonu için denetim izi de sağlar; bu konu API dokümantasyonu depo güvenliği açısından önemlidir.

“Git ile çalışmak” pratikte ne demek?

Bir aracın GitHub logosu göstermesi yeterli değildir. Gerçekten Git dostu bir API aracı şu özellikleri sağlamalıdır:

• Dosya tabanlı depolama: YAML, JSON, Markdown veya belgelenmiş düz metin formatı kullanmalı.
• Çift yönlü senkronizasyon: Araçta yapılan değişiklik depoya, depodaki değişiklik araca yansımalı.
• Dal ve merge desteği: Farklı branch'ler arasında çalışırken veri modeli bozulmamalı.
• CI çalıştırıcısı: Aynı test veya doğrulama komut satırından çalıştırılabilmeli.
• Diff okunabilirliği: PR'daki değişiklikler insan tarafından incelenebilir olmalı.

Hepsi bir arada: Apidog

Apidog, API tasarımı, hata ayıklama, test, mock ve dokümantasyonu tek bir OpenAPI merkezli iş akışında birleştirir. Git ile senkronize çalışan spesifikasyon sayesinde ekip, API yaşam döngüsünü ayrı araçlara bölmeden sürüm kontrolüne alabilir.

Pratik akış şöyle görünür:

1. OpenAPI spesifikasyonunu depoya koyun.
2. Apidog'u bu depoya bağlayın.
3. Endpoint'i Apidog içinde tasarlayın veya düzenleyin.
4. Mock, test senaryosu ve dokümantasyonu aynı spesifikasyondan üretin.
5. Değişiklikleri branch üzerinden PR'a taşıyın.
6. CI'da testleri çalıştırın.

Apidog'un Git entegrasyonu ve senkronizasyonu, GitHub, GitLab ve self-hosted Git kurulumlarıyla bağlantı kurar. Spesifikasyon odaklı yaklaşımı detaylandırmak için spesifikasyon odaklı mod kılavuzuna bakabilirsiniz.

En iyi kullanım alanı: Tasarım, test, mock ve dokümantasyonu tek bir sürüm kontrollü API kaynağından yönetmek isteyen ekipler.

Git dostu API istemcileri: Bruno ve Insomnia

Sadece istek göndermek ve koleksiyonları Git'te saklamak istiyorsanız dosya tabanlı istemciler yeterli olabilir.

Bruno

Bruno, istekleri sahip olduğunuz bir klasörde .bru dosyaları olarak saklar. Zorunlu bulut senkronizasyonu yoktur; koleksiyon dosyaların kendisidir.

Örnek yaklaşım:

api-requests/
  orders/
    get-orders.bru
    create-order.bru
  users/
    get-user.bru

Bu yapı sayesinde istek değişiklikleri normal Git diff olarak görünür. Bruno'nun yaklaşımını Bruno istek odaklı vs. tasarım odaklı karşılaştırmasında ele aldık.

Insomnia

Insomnia, koleksiyonları ve ortamları Git Sync ile depoya bağlayabilir. Daha geleneksel ve görsel bir API istemcisi isteyen ekipler için uygundur. Başlangıç için Insomnia API test rehberi temel akışı gösterir.

En iyi kullanım alanı: API koleksiyonlarını depoda saklamak isteyen, ancak tüm yaşam döngüsünü tek platformda yönetmeye ihtiyaç duymayan geliştiriciler. Alternatifler için en iyi Postman alternatifleri listesine bakabilirsiniz.

API tasarım ve spesifikasyon araçları: Stoplight ve Redocly

Bu araçlar, OpenAPI dosyasını merkezi yapı olarak kabul eder ve Git tabanlı tasarım akışını destekler.

Stoplight

Stoplight, OpenAPI dosyasını görsel olarak düzenlemenizi sağlar. Depodaki spesifikasyonu okuyup yazabilir ve stil kurallarıyla tutarlılığı artırabilir.

Redocly

Redocly, OpenAPI yönetimi, linting, çok dosyalı spesifikasyon yapıları ve dokümantasyon üretimi tarafında güçlüdür. API-first ekipler için CI'a uygun kontroller sağlar.

Örnek CI fikri:

name: api-checks

on:
  pull_request:

jobs:
  lint-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI
        run: npx @redocly/cli lint api/openapi.yaml

Bu yaklaşım Git ile OpenAPI sürüm kontrolü modeline uyar. Spesifikasyonu sağlam tutmak için ayrıca OpenAPI doğrulayıcı kullanabilirsiniz.

En iyi kullanım alanı: API tasarım kurallarını wiki yerine CI içinde uygulamak isteyen ekipler.

Dokümantasyon: Mintlify, Fern ve ReadMe

Kod olarak dokümantasyon, API belgelerinin depodaki Markdown ve OpenAPI dosyalarından oluşturulmasıdır. Böylece dokümanlar API'den kopmaz.

Mintlify

Mintlify, Markdown ve OpenAPI dosyalarını depodan senkronize eder, değişikliklerde yeniden oluşturur ve branch preview akışlarını destekler.

Fern

Fern, tek bir spesifikasyondan dokümantasyon ve SDK üretmeye odaklanır. Böylece yayımlanan referans ile istemci kodu aynı kaynaktan türeyebilir.

ReadMe

ReadMe, Git'ten içerik senkronize edebilen geliştirici portalı sağlar. Özellikle herkese açık API portalları için uygundur.

Bu konuyu Git entegrasyonlu API belgeleri yazısında daha detaylı ele alıyoruz.

En iyi kullanım alanı: API dokümantasyonunun her merge sonrası otomatik güncellenmesini isteyen ekipler.

Test ve CI: Newman, Step CI ve Schemathesis

API testleri depoda yaşıyorsa CI içinde otomatik çalıştırılabilir.

Newman

Newman, Postman koleksiyonlarını komut satırından çalıştırır. Koleksiyon JSON dosyaları depoya commit edilirse CI'da kullanılabilir.

İlgili karşılaştırmalar:

• Newman vs Postman
• Postman CLI vs Newman

Step CI

Step CI, YAML iş akışlarıyla API kontrolleri tanımlamanızı sağlar. Test tanımı kodun yanında yaşar.

Schemathesis

Schemathesis, OpenAPI spesifikasyonunu okuyarak property-based testler üretir. Spesifikasyondan doğan sözleşme ihlallerini yakalamak için kullanışlıdır.

Apidog da CLI çalıştırıcısı sunar; böylece senkronize spesifikasyona bağlı test senaryolarını aynı pipeline içinde çalıştırabilirsiniz.

En iyi kullanım alanı: Her PR'da API sözleşmesini otomatik doğrulamak isteyen ekipler.

Git dostu API araçları karşılaştırması

Araç	Kategori	Şu şekilde saklar	Git senkronizasyonu	CI çalıştırıcı
Apidog	Hepsi bir arada	OpenAPI + proje dosyaları	Evet (GitHub/GitLab/self-host)	Evet
Bruno	İstemci	.bru metin dosyaları	Evet (dosyalar koleksiyondur)	Evet
Insomnia	İstemci	Koleksiyon dosyaları	Evet (Git Sync)	Evet
Stoplight	Tasarım	OpenAPI dosyası	Evet	CLI aracılığıyla
Redocly	Tasarım/belgeler	OpenAPI + Markdown	Evet	Evet
Mintlify	Belgeler	Markdown + OpenAPI	Evet (çift yönlü)	Evet
Fern	Belgeler/SDK	Spec + yapılandırma	Evet	Evet
Newman	Test	Postman JSON	Depo aracılığıyla	Evet
Step CI	Test	YAML iş akışları	Evet	Evet

API iş akışınızı Git'e nasıl taşırsınız?

Her şeyi tek seferde dönüştürmek zorunda değilsiniz. Uygulanabilir bir geçiş planı:

1. OpenAPI spesifikasyonunu depoya koyun

Önce API sözleşmesini kodun yanına alın:

mkdir -p api
cp openapi.yaml api/openapi.yaml
git add api/openapi.yaml
git commit -m "Add OpenAPI specification"

Bu tek adım bile geçmiş, review ve rollback sağlar. Mekanik için OpenAPI spesifikasyonunu GitHub ile senkronize etme kılavuzuna bakabilirsiniz.

2. Git dostu aracı kanonik dosyaya bağlayın

Apidog, Bruno, Stoplight veya Redocly gibi aracı depodaki dosyaya yönlendirin. Amaç, aracın kendi kopyasını değil, depodaki dosyayı doğruluk kaynağı kabul etmesidir.

3. CI kontrolleri ekleyin

Başlangıç için minimum kontroller:

name: api-ci

on:
  pull_request:

jobs:
  validate-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate OpenAPI
        run: npx @redocly/cli lint api/openapi.yaml

Daha sonra contract test, mock sunucu testi veya Schemathesis gibi kontroller ekleyebilirsiniz.

4. API değişiklikleri için branch kullanın

Her API değişikliğini kod değişikliği gibi yönetin:

git checkout -b feature/add-order-status
# kod + openapi + test + docs değişiklikleri
git push origin feature/add-order-status

Bu yapı, Git-yerel API geliştirme yaklaşımının pratik karşılığıdır.

Örnek PR akışı: status alanı ekleme

Bir geliştiricinin orders endpoint'ine status alanı eklediğini düşünün.

1. Branch açılır

git checkout -b feature/order-status

2. OpenAPI sözleşmesi güncellenir

Örnek değişiklik:

Order:
  type: object
  properties:
    id:
      type: string
      example: ord_123
    status:
      type: string
      enum: [pending, paid, shipped, cancelled]
      example: paid

3. Test senaryosu eklenir

- name: order includes status
  request:
    method: GET
    url: /orders/ord_123
  expect:
    status: 200
    json:
      status: paid

4. Dokümantasyon aynı spesifikasyondan güncellenir

Eğer dokümantasyon OpenAPI'den üretiliyorsa manuel kopyalama gerekmez. Referans sayfası yeni alanı otomatik yansıtır.

5. PR açılır

Review eden kişi tek diff içinde şunları görür:

api/openapi.yaml
api/tests/orders.yaml
src/orders/*

6. CI merge kararını destekler

Pipeline:

• OpenAPI lint çalıştırır.
• Sözleşme testlerini yürütür.
• Mock veya staging ortamına karşı istekleri kontrol eder.
• Hata varsa merge'i durdurur.

Bu modelde ayrı GUI çalışma alanında unutulan değişiklik kalmaz; her şey tek PR içinde incelenir.

Git tabanlı API araçlarına geçerken yapılan yaygın hatalar

Hata 1: Export dosyasını sürüm kontrolü sanmak

Bir koleksiyonu ara sıra JSON olarak dışa aktarmak sürüm kontrolü değildir. Bu sadece snapshot'tır. Gerçek kaynak hâlâ bulut çalışma alanındaysa Git sadece yedek olur.

Hata 2: İki doğruluk kaynağı tutmak

Depoda OpenAPI dosyası, ayrı araçta elle güncellenen koleksiyon ve başka yerde dokümantasyon tutmak drift üretir. Mümkün olduğunca hepsini tek spesifikasyondan türetin.

Hata 3: CI eklememek

Spesifikasyonu Git'e koyup doğrulama çalıştırmamak eksik bir geçiştir. En azından lint ve schema validation ekleyin.

Hata 4: Devasa tek dosya spesifikasyonla devam etmek

Büyük openapi.yaml dosyaları merge conflict çıkarabilir. Gerekirse spesifikasyonu parçalara ayırın:

api/
  openapi.yaml
  paths/
    orders.yaml
    users.yaml
  components/
    schemas/
      Order.yaml
      User.yaml

Hata 5: Branch kuralı belirlememek

API değişiklikleri için açık bir kural koyun:

• Her breaking change ayrı branch.
• OpenAPI değişmeden endpoint merge edilmez.
• Test eklenmeden yeni endpoint merge edilmez.
• Dokümantasyon aynı PR'da güncellenir veya otomatik üretilir.

Git tabanlı API yığınızı Apidog ile test edin ve yayınlayın

Spesifikasyon Git'te yaşadığında, her branch'te onu kullanabilen bir araca ihtiyaç duyarsınız. Apidog, senkronize OpenAPI dosyasını okuyarak canlı isteklere, mock sunuculara, test senaryolarına ve dokümantasyona dönüştürür.

Uygulanabilir kurulum:

1. Repo spesifikasyonunu içe aktarın. İstekler ve testler elle sürdürülen kopyalardan değil, kanonik OpenAPI dosyasından türesin.
2. Ortamları tanımlayın. Aynı testleri local, staging ve production endpoint'lerine yönlendirin.
3. CLI'ı CI içinde çalıştırın. PR açıldığında contract testler otomatik çalışsın.
4. Belgeleri aynı spesifikasyondan üretin. Yayınlanan dokümantasyon tasarımdan geride kalmasın.
5. Branch bazlı değişiklikleri review edin. Sözleşme, test ve dokümantasyon aynı PR'da görünür olsun.

Bu, “GitHub entegrasyonu olan araç” ile “sürüm kontrollü API iş akışı için tasarlanmış araç” arasındaki farktır. İlk depo destekli projenizi bağlamak için Apidog'u indirin.

Sıkça Sorulan Sorular

Bir API aracının Git ile çalışması ne anlama gelir?

Aracın API varlıklarını commit edilebilir, branch'lenebilir ve review edilebilir dosyalar olarak saklaması anlamına gelir. Daha güçlü araçlar bu dosyaları depoyla çift yönlü senkronize eder ve CI için komut satırı çalıştırıcısı sağlar.

Postman Git dostu bir API aracı mıdır?

Postman bulut öncelikli çalışır. Koleksiyonlar genellikle Postman çalışma alanında yaşar; Git erişimi ise yerel dosya tabanlı çalışma yerine entegrasyonlarla sağlanır. Gerçek sürüm kontrolü isteyen ekipler Bruno gibi dosya tabanlı istemcilere veya Apidog gibi hepsi bir arada araçlara yönelebilir. Seçenekler için en iyi Postman alternatifleri listesine bakın.

OpenAPI spesifikasyonumu Git'te tutup yine de görsel araç kullanabilir miyim?

Evet. Apidog, Stoplight ve Redocly gibi araçlar bunun için kullanılır. OpenAPI dosyası depoda kanonik kalır; araç sadece düzenleme, test, dokümantasyon veya doğrulama arayüzü sağlar.

Bunun kod olarak dokümantasyondan farkı nedir?

Kod olarak dokümantasyon sadece belgeleri dosya tabanlı yönetir. Git tabanlı API iş akışı ise aynı modeli spesifikasyonlara, request koleksiyonlarına, mock'lara ve testlere genişletir.

Git dostu API araçları GitLab ve self-hosted Git ile çalışır mı?

Birçoğu çalışır. Apidog, GitHub, GitLab ve self-hosted örneklerle bağlantı kurar. Bruno gibi dosya tabanlı istemcilerde ise dosyalar düz metin olduğu için herhangi bir Git sağlayıcısıyla kullanılabilir.

Her şeyi bir kerede Git'e taşımam gerekiyor mu?

Hayır. En pratik sıra:

1. OpenAPI spesifikasyonunu depoya koyun.
2. Git dostu aracı bu dosyaya bağlayın.
3. CI doğrulaması ekleyin.
4. Testleri ve dokümantasyonu aynı kaynaktan üretin.
5. Her API değişikliğini branch + PR ile yönetin.

API araçlarını Git'e koymak ekibi yavaşlatır mı?

İlk kurulum biraz disiplin ister; ancak sonrasında review, otomatik test ve değişiklik geçmişi ekibi hızlandırır. “Bunu kim değiştirdi?” sorusu toplantı yerine Git geçmişiyle cevaplanır.

Bir araya getirmek

Git dostu API araçlarının ortak deseni nettir: API çalışmasını dosya olarak saklayın ve Git'in iyi yaptığı işleri kullanın. İhtiyaca göre seçim yapın:

• Tüm API yaşam döngüsü için: Apidog
• Dosya tabanlı istek istemcisi için: Bruno veya Insomnia
• Spesifikasyon yönetimi için: Stoplight veya Redocly
• Kod olarak dokümantasyon için: Mintlify, Fern veya ReadMe
• CI testleri için: Newman, Step CI veya Schemathesis

Başlamak için OpenAPI spesifikasyonunuzu commit edin. Ardından Apidog'u depoya bağlayarak tasarım, test, dokümantasyon ve mock akışlarını ekibinizin zaten kullandığı Git review sürecine taşıyın.