Postman Koleksiyonları Neden Tek Doğruluk Kaynağı Değil (ve Çözümleri)

Postman koleksiyonları ile OpenAPI belirtimi arasındaki fark, ekip büyüdükçe kritik hale gelir. Altı ay önce oluşturduğunuz bir koleksiyon; artık üç yeni zorunlu alanı, iki kullanım dışı parametreyi ve gerçek sunucu yanıtıyla uyuşmayan bir response yapısını temsil ediyor olabilir. Bu sırada Git'teki OpenAPI belirtimi başka bir şey, Swagger UI başka bir şey söylüyorsa sorun araçta değil, iş akışındadır.

Apidog'u bugün deneyin

Postman; istek çalıştırma, betikleme ve keşif testi için güçlüdür. Ancak koleksiyonu API sözleşmesinin kendisi gibi kullanmak, zamanla sapma üretir. Daha sürdürülebilir model şudur: OpenAPI belirtimi kaynak olur, Postman koleksiyonu bu belirtimden üretilen bir çıktı olur.

💡 Bu bağımlılığı tersine çevirdiğinizde sapma azalır. Apidog, belirtim odaklı iş akışını işbirliği, mock, test ve CI/CD ile bağlayarak ekibin aynı API kaynağı üzerinden çalışmasına yardımcı olur. Mevcut Postman çalışmalarınızı çöpe atmadan bu modele geçebilirsiniz.

Koleksiyonlar neden sapar?

Postman koleksiyonu istek odaklıdır:

• Bir endpoint çağırırsınız.
• Yanıtı gözlemlersiniz.
• İsteği kaydedersiniz.
• Zamanla değişkenler, pre-request script'ler, test assertion'ları ve klasör yapıları eklersiniz.

Bu yapı, API'nin resmi sözleşmesinden çok ekibin API'yi nasıl çağırdığını gösterir.

OpenAPI belirtimi ise sözleşme odaklıdır. Endpoint'leri, parametreleri, şemaları ve yanıtları makine tarafından okunabilir şekilde tanımlar. Araçlar bu dosyadan doğrulama, mock, dokümantasyon ve kod üretimi yapabilir.

İki yapı farklı sorulara cevap verir:

• Postman koleksiyonu: “Bu endpoint'i bugün nasıl çağırırım?”
• OpenAPI belirtimi: “Bu API ne yapmalı?”

Sorun, ekipler bu iki dosyayı bağımsız güncellediğinde başlar. Bir geliştirici PR içinde OpenAPI dosyasını değiştirir. Başka biri bozulan testi düzeltmek için koleksiyonu günceller. İki değişiklik birleşmez. Birkaç ay sonra aynı API'nin iki kısmen doğru açıklaması oluşur.

Inventis Korea'nın yaşadığı sorun da buydu: ekip API oluşturuyor, Swagger için OpenAPI belirtimi üretiyor, test için koleksiyonu Postman'e aktarıyor ve ardından üç temsili senkron tutmaya çalışıyordu. Koleksiyon tam şemayı yansıtmadığı için testler bazı edge case'leri kaçırıyordu. Belirtim testlerin girdisi olmadığı için dokümantasyon sapıyordu.

Temel neden: Postman bir belirtim deposu değildir

Postman koleksiyonlarının kendi formatı vardır. Postman koleksiyon şeması, istekleri, script'leri ve klasör hiyerarşilerini tanımlayan JSON tabanlı bir formattır. OpenAPI değildir.

Postman OpenAPI içe ve dışa aktarabilir, ancak bu dönüşüm her zaman birebir değildir:

• OpenAPI → Postman dönüşümünde şema ayrıntılarının bir kısmı koleksiyonda temsil edilemeyebilir.
• Postman → OpenAPI dönüşümünde script'ler, testler ve runtime verileri belirtime aktarılamayabilir.

Bu Postman'in zayıflığı değil, tasarım sınırıdır. Postman istek yürütme merkezlidir; OpenAPI ise sözleşme tanımı merkezlidir.

Özellik	Postman koleksiyonu	OpenAPI belirtimi
İstek parametreleri	Anahtar-değer çiftleri olarak tutulur	Tür, required, schema ve doğrulama bilgileriyle tanımlanır
Yanıt yapısı	Opsiyonel örnek olarak saklanır	JSON Schema ile tanımlanır
Hata yanıtları	Her isteğe manuel eklenir	responses altında standartlaştırılır
Şema yeniden kullanımı	Genellikle kopyala-yapıştır	components/schemas ve $ref ile yapılır
Makine tarafından okunabilir sözleşme	Sınırlı	Evet
Git diff uygunluğu	Opak JSON nedeniyle zor	YAML/JSON üzerinde anlamlı diff alınabilir
Lint ve doğrulama	Yerel koleksiyon formatında sınırlı	Spectral, Redocly CLI vb. ile yapılabilir

Sonuç: koleksiyon sözleşmeyi tam ifade edemediği için gerçek sözleşme başka yerde yaşar. Bir dosya güncellenip diğeri güncellenmediğinde sapma başlar.

Belirtim odaklı yaklaşım nedir?

Belirtim odaklı yaklaşım, “önce aylarca YAML yazın, sonra kodlayın” demek değildir. Pratik anlamı şudur:

1. OpenAPI belirtimi Git'te API'nin yetkili kaynağı olur.
2. Dokümantasyon, mock'lar, testler ve koleksiyonlar bu belirtimden üretilir.
3. API değişikliği önce belirtimde yapılır.
4. Aşağı akış çıktıları otomatik veya araçlar aracılığıyla güncellenir.

Belirtim odaklı metodoloji, Postman koleksiyonunu kaldırmak zorunda değildir. Sadece koleksiyonun yönünü değiştirir: koleksiyon artık kaynak değil, çıktıdır.

Pratik akış:

1. openapi.yaml Git'e kaydedilir.
2. PR içinde gözden geçirilir.
3. CI içinde lint edilir.
4. Mock, dokümantasyon ve test koleksiyonu belirtimden oluşturulur.
5. Testler oluşturulan koleksiyona karşı çalışır.

Bu modelde Postman hâlâ kullanılabilir. Pre-request script'leriniz, environment değişkenleriniz ve keşif testleriniz devam eder. Fark şudur: request yapısı manuel tutulan bir koleksiyondan değil, OpenAPI belirtiminden gelir.

OpenAPI belirtiminden Postman koleksiyonu üretme

Bir OpenAPI dosyasından Postman uyumlu koleksiyon üretmek için Redocly CLI ve openapi-to-postmanv2 kullanabilirsiniz.

# Redocly CLI'yi yükleyin
npm install -g @redocly/cli

# OpenAPI belirtimini doğrulayın
redocly lint openapi/petstore.yaml

# $ref zincirlerini çözerek tek dosya üretin
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml

# Postman Collection v2.1 formatına dönüştürün
npm install -g openapi-to-postmanv2

openapi2postmanv2 \
  --spec dist/petstore-bundled.yaml \
  --output dist/petstore-collection.json \
  --prettyPrint

Çıktı standart bir Postman koleksiyonu JSON dosyasıdır:

dist/petstore-collection.json

Bunu şu şekilde kullanabilirsiniz:

• Postman'e import edebilirsiniz.
• Newman ile CI içinde çalıştırabilirsiniz.
• Postman CLI için temel koleksiyon olarak kullanabilirsiniz.

Önemli nokta: koleksiyonu elle düzenlemek yerine her çalıştırmada belirtimden yeniden üretirsiniz.

CI içinde koleksiyonu otomatik üretme

Aşağıdaki GitHub Actions örneği, her API değişikliğinde belirtimi lint eder, koleksiyonu üretir ve Newman ile testleri çalıştırır.

# .github/workflows/api-tests.yml
name: API sözleşme testleri

on:
  push:
    paths:
      - "openapi/**"
      - "src/**"

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Bağımlılıkları yükle
        run: |
          npm install -g @redocly/cli openapi-to-postmanv2 newman

      - name: OpenAPI belirtimini doğrula
        run: redocly lint openapi/petstore.yaml

      - name: Belirtimden koleksiyon oluştur
        run: |
          mkdir -p dist
          redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
          openapi2postmanv2 \
            --spec dist/petstore-bundled.yaml \
            --output dist/petstore-collection.json \
            --prettyPrint

      - name: Oluşturulan koleksiyona karşı testleri çalıştır
        run: |
          newman run dist/petstore-collection.json \
            --environment config/env-staging.json \
            --reporters cli,junit \
            --reporter-junit-export results/test-results.xml

      - name: Test sonuçlarını yükle
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: results/

Bu kurulumla belirtim her test çalıştırmasının girdisi olur. Bir PR belirtimi bozarsa, sorun aynı PR içinde yakalanır.

Apidog bu iş akışına nasıl uyuyor?

Apidog'un amacı Postman'i sadece bir istek yürütücü olarak değiştirmek değildir. Asıl değer, OpenAPI belirtimini işbirliği, mock, dokümantasyon ve test katmanlarıyla bağlamasıdır.

Apidog'un Belirtim Odaklı Modu şu anda beta aşamasındadır. Bu mod ile bir OpenAPI belirtimini Git deposundan Apidog çalışma alanına senkronize edebilirsiniz.

Bu senkronize belirtimden şunlar üretilebilir:

• Otomatik mock'lar
• Etkileşimli API dokümantasyonu
• Test senaryoları
• Ekip içinde ortak çalışma yüzeyleri

Belirtim Git'te değiştiğinde Apidog tarafındaki yüzeyler de aynı kaynağa göre güncellenir. Böylece ayrı bir koleksiyon, ayrı bir dokümantasyon aracı ve ayrı bir mock sunucusunu manuel senkron tutma ihtiyacı azalır.

STC Group ve Dünya Ekonomik Forumu'nun açıkladığı gibi ekipler genellikle üç ayrı sistemle çalışır:

1. Test için Postman
2. Belirtim/dokümantasyon için ayrı araç
3. Frontend geliştirme için mock sunucusu

Belirtim odaklı modelde bu üç yüzey aynı OpenAPI kaynağından beslenir.

Büyük ekiplerde, özellikle DHL dağıtımında görülen 100+ kullanıcı gibi senaryolarda, Apidog'un çalışma alanı izinleri ve SSO özelliklerinin ihtiyaçlarınıza uyup uymadığını deneme sırasında doğrulamak gerekir. Bu, üretime almadan önce yapılması gereken makul bir POC adımıdır.

Mevcut Postman koleksiyonlarınız varsa, başlangıç noktası olarak Apidog'a dönüştürebilir ve ardından belirtimi ileriye dönük standart kaynak yapabilirsiniz.

OpenAPI belirtimini Git'te kod gibi yönetin

API belirtimi-kod olarak yaklaşımı, OpenAPI dosyasının uygulama kodu gibi yönetilmesi anlamına gelir:

• Pull request
• Code review
• CI lint
• Sürüm etiketi
• Branch stratejisi

Başlamak için uygulanabilir adımlar:

1. Belirtimi servis reposunda tutun

Belirtimi ayrı bir “docs” reposuna koymak yerine, tanımladığı servisle aynı repoda saklayın.

Örnek yapı:

service-a/
  src/
  openapi/
    openapi.yaml
  .github/
    workflows/
      api-tests.yml

Böylece API davranışı ve API sözleşmesi aynı PR içinde değişir.

2. CI içine Spectral ekleyin

Spectral, OpenAPI dosyanızı OpenAPI belirtimine ve özel kurallarınıza göre doğrular.

Basit kurulum:

npm install -g @stoplight/spectral-cli
spectral lint openapi/openapi.yaml

GitHub Actions adımı:

- name: OpenAPI lint
  run: |
    npm install -g @stoplight/spectral-cli
    spectral lint openapi/openapi.yaml

Bu sayede şu problemler review yorumuna kalmadan CI hatasına dönüşür:

• Bozuk $ref
• Eksik response tanımı
• Tutarsız endpoint adlandırması
• Eksik açıklamalar
• Geçersiz schema yapıları

3. Bozucu değişiklikler için branch kullanın

Breaking change içeren API değişikliklerini doğrudan ana dala göndermeyin. Uygulama kodunda yaptığınız gibi belirtim için de branch kullanın.

Örnek:

main
feature/add-billing-v2
breaking/remove-legacy-customer-field

Apidog çalışma alanları belirtim üzerinde dallanmayı destekler. Böylece bir ekip kararlı branch ile çalışırken başka bir ekip bozucu değişikliği inceleyebilir.

4. Tüketici servislerde belirtim sürümünü sabitleyin

Servis B, Servis A'nın sözleşme testlerine bağımlıysa main branch'in son haline değil, belirli bir sürüm etiketine bağlanmalıdır.

Örnek:

service-a-openapi@v1.8.0

Bu, tüketici testlerinin beklenmedik şekilde kırılmasını önler.

Daha ayrıntılı kurulum için Git-yerel API iş akışı kılavuzuna bakabilirsiniz.

Sıkça Sorulan Sorular

Postman'i tamamen bırakmak zorunda mıyım?

Hayır. Değişiklik araçtan çok bağımlılık yönüyle ilgilidir. Postman'i keşif testi, manuel deneme ve script tabanlı akışlar için kullanmaya devam edebilirsiniz.

Fark şu olur: koleksiyonu manuel sürdürülen bir kaynak olarak değil, OpenAPI belirtiminden üretilen bir çıktı olarak ele alırsınız.

Mevcut Postman script'leri ve environment değişkenleri ne olur?

Pre-request script'ler, test script'leri ve environment değişkenleri ayrı dosyalar olarak korunabilir. Koleksiyonu belirtimden yeniden oluştururken bu davranışsal katmanı ayrı yönetirsiniz.

Önerilen ayrım:

openapi/
  openapi.yaml

postman/
  env-staging.json
  env-prod.json
  scripts/

Yapısal katman OpenAPI'den gelir. Runtime davranışı ayrı tutulur.

Henüz belirtimde olmayan endpoint'leri nasıl ele alırım?

Belirtim odaklı iş akışında belirtimde olmayan endpoint test için hazır değildir. Bu bilinçli bir kapıdır.

Önerilen akış:

1. Yeni endpoint için OpenAPI girdisini ekleyin.
2. PR içinde schema, request ve response tanımlarını inceletin.
3. Mock veya stub ile frontend/backend paralel geliştirme yapın.
4. Test koleksiyonunu belirtimden üretin.

Belirtim düzenleme ve doğrulama araçları için en iyi OpenAPI doğrulayıcı araçları kılavuzuna bakabilirsiniz.

Apidog Belirtim Odaklı Modu kullanılabilir mi?

Apidog Belirtim Odaklı Modu şu anda beta aşamasındadır. Apidog üzerinden erişebilir ve Git senkronizasyonu, branch desteği ve otomatik mock özelliklerini kendi API yapınızla test edebilirsiniz.

Beta özelliklerde olduğu gibi, üretim iş akışına almadan önce gerçek belirtiminizle POC yapmanız önerilir.

Belirtimi Postman'e import etmekten farkı ne?

Postman'e OpenAPI import etmek tek seferlik dönüşümdür. Import sonrası koleksiyon belirtimden bağımsız yaşamaya başlar ve sapma tekrar oluşur.

Belirtim odaklı modelde koleksiyon her CI çalıştırmasında veya senkronizasyonda yeniden oluşturulur. Böylece koleksiyon, belirtimden en fazla bir build kadar geride kalır.

Sonuç

Postman koleksiyonu ile OpenAPI belirtimi arasındaki sapma Postman hatası değildir. Sorun, iki kısmen çakışan API açıklamasını net bir kaynak ilişkisi olmadan sürdürmektir.

Daha sağlam model:

1. OpenAPI belirtimini Git'te yetkili kaynak yapın.
2. Belirtimi PR ve CI süreçlerine dahil edin.
3. Postman koleksiyonunu belirtimden üretin.
4. Test, mock ve dokümantasyonu aynı kaynaktan besleyin.

Bu tersine çevirme bakım yükünü azaltır. Testleri bozan belirtim değişiklikleri aynı PR içinde yakalanır. Dokümantasyon, mock'lar ve test senaryoları aynı sözleşmeye bağlı kalır.

Apidog'u indirin ve mevcut OpenAPI belirtiminizle Belirtim Odaklı Mod çalışma alanı açın. Eğer başlangıç noktanız bir Postman koleksiyonuysa, koleksiyonu OpenAPI'ye geçiş için ara adım olarak kullanabilir ve sonrasında belirtim odaklı iş akışına geçebilirsiniz.