Swagger ve Postman Koleksiyonları Arasındaki Senkronizasyon Sorunları (ve Çözümleri)

Swagger Postman kayması bir süreç hatası değildir. Aynı API sözleşmesini, onları senkronize tutacak hiçbir mekanizma olmadan iki ayrı yerde sakladığınızda ortaya çıkar. Bir openapi.yaml yazarsınız, Swagger UI belgeleri buradan üretir, sonra testler için bir Postman koleksiyonu dışa aktarırsınız. Bir hafta sonra biri koleksiyonda bir uç noktayı değiştirir, YAML aynı kalır ve artık belgeler ile testler farklı API'leri tarif eder. Bir spesifikasyondan test oluşturma adımları için OpenAPI test üretimi kılavuzuna bakabilirsiniz.

Apidog'u bugün deneyin

💡 Apidog kullanan ekipler, OpenAPI dosyasını belgeleri, mock sunucuları ve testleri yönlendiren tek yapıt olarak ele alır. Yapısal çözüm daha sıkı manuel inceleme değil, kaymaya neden olan ikinci sözleşme kopyasını ortadan kaldırmaktır.

İki dosya neden her zaman birbirinden uzaklaşır?

Tipik kurulum şudur:

• Depoda bir openapi.yaml vardır.
• Test ekibi veya backend geliştiricileri ayrıca bir Postman koleksiyonu tutar.
• Swagger UI yalnızca YAML'den belge üretir.
• Postman koleksiyonu ayrı bir çalışma alanında değişir.

Bu iki yapıt aynı API sözleşmesini temsil eder, ancak birbirlerini doğrulamaz.

Örnek senaryo:

1. Backend ekibi yeni bir POST /payments/refund uç noktası yayınlar.
2. Yeni istek gövdesinde zorunlu reason alanı vardır.
3. QA, testleri çalıştırmak için uç noktayı Postman koleksiyonuna ekler.
4. openapi.yaml güncellemesi sonraki sprint'e kalır.
5. Frontend geliştirici Swagger belgesine bakarak endpoint'i reason olmadan çağırır.
6. API 400 döner, ancak Swagger belgesi hatayı açıklamaz.

Sorun ihmal değildir. Sorun, iki ayrı sözleşme kopyasının hiçbir bağlayıcı mekanizma olmadan yaşamasıdır.

Yapıt	Kim günceller	Güncelleme tetikleyicisi	Doğrulama
openapi.yaml	API tasarımcısı / teknik lider	Planlanmış belge sprint'i	İsteğe bağlı linter, örn. Spectral
Postman koleksiyonu	QA / backend geliştirici	Test gerektiğinde	Manuel inceleme veya yok
Swagger UI görünümü	YAML'den otomatik oluşturulur	Sadece YAML değiştiğinde	YAML'yi yansıtır, gerçek API'yi değil

YAML için Spectral gibi bir linter çalıştırmak faydalıdır. Ancak linter yalnızca spesifikasyon içindeki sorunları yakalar. YAML ile Postman koleksiyonu arasındaki farkı yakalamaz.

Üç kopya problemi

Stoplight, Swagger UI veya wiki tabanlı ayrı bir dokümantasyon katmanı kullanıyorsanız problem büyür. Artık sözleşmenin üç kopyası vardır:

1. Git'e işlenmiş openapi.yaml
2. Dışa aktarılmış Postman koleksiyonu
3. Stoplight, Swagger UI veya wiki üzerinde oluşturulan dokümantasyon

Her kopya bağımsız olarak kayabilir.

OpenAPI Spesifikasyonu bir açıklama formatıdır. Çalışma zamanında API davranışını zorlamaz ve Postman koleksiyonunuzun aynı sözleşmeye uyduğunu garanti etmez.

Bu nedenle ekip büyüdükçe bakım maliyeti artar:

• Daha fazla servis
• Daha fazla endpoint
• Daha fazla test koleksiyonu
• Daha fazla manuel senkronizasyon
• Daha fazla kayma riski

Kayma testleri nasıl sessizce bozar?

Swagger Postman kaymasının en tehlikeli tarafı şudur: testler yanlış olsa bile geçmeye devam edebilir.

Örneğin güncel OpenAPI spesifikasyonunuz şöyle olsun:

# openapi.yaml - güncellenmiş spesifikasyon (v2)
paths:
  /payments/refund:
    post:
      summary: Geri ödeme başlat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_id
                - reason          # v2'de eklenen yeni zorunlu alan
              properties:
                transaction_id:
                  type: string
                  example: "txn_8x9Ka21"
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]
                  example: "requested_by_customer"
      responses:
        '200':
          description: Geri ödeme başlatıldı
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund_id:
                    type: string
                  status:
                    type: string

Ama Postman koleksiyonunuz hâlâ v1 isteğini gönderiyor olabilir:

{
  "transaction_id": "txn_8x9Ka21"
}

Eğer backend geçiş dönemi için reason alanına varsayılan bir değer veriyorsa, Postman testi yeşil kalır. Fakat spesifikasyon artık reason alanını zorunlu kabul eder.

Sonuç:

• Test geçer.
• Spesifikasyon farklı bir sözleşme söyler.
• Frontend entegrasyonu staging'de kırılabilir.
• Kırılma, test çıktısından anlaşılmaz.

YAML'nize uygun bir OpenAPI doğrulayıcı çalıştırmak şema hatalarını yakalar. Ancak spesifikasyon ile Postman koleksiyonunun gerçekten gönderdiği istekler arasındaki farkı yakalamaz.

OpenAPI odaklı test ne anlama gelir?

OpenAPI odaklı testte spesifikasyon yetkili kaynaktır.

Yani:

• Testler spesifikasyondan türetilir.
• Belgeler spesifikasyondan türetilir.
• Mock sunucu spesifikasyondan türetilir.
• Ayrı bir sözleşme kopyası tutulmaz.

Bu, “Swagger'ı Postman'a aktarmak” ile aynı şey değildir.

Aktarım tek seferlik bir kopyalama işlemidir:

1. openapi.yaml dosyasını Postman'a aktarırsınız.
2. Bir koleksiyon oluşur.
3. Bu andan sonra YAML ve koleksiyon tekrar bağımsız hale gelir.
4. Sonraki her değişiklikte tekrar manuel aktarım gerekir.

Bu kaymayı çözmez; sadece sıfırlar.

Spesifikasyon-önce iş akışı ise şöyle çalışır:

1. openapi.yaml Git'te ana sözleşme olarak yaşar.
2. Araç bu dosyadan dokümantasyon, mock ve test üretir.
3. Pull request ile YAML değiştiğinde alt çıktılar da güncellenir.
4. Senkronize tutulacak ayrı bir Postman koleksiyonu kalmaz.

Spesifikasyon-önce API geliştirme modeli bu yaklaşımın daha geniş iş akışını açıklar. Buradaki odak, belgeler ve testler arasındaki kaymayı ortadan kaldırmaktır.

Apidog'u tek spesifikasyon üzerinde yürütme katmanı olarak kullanma

Apidog modeli şu varsayıma dayanır:

• Git gerçeklik kaynağıdır.
• openapi.yaml ana sözleşmedir.
• Apidog bu sözleşme üzerinden dokümantasyon, mock ve test üretir.

Akış pratikte şöyle görünür:

openapi.yaml
    ├── Dokümantasyon
    ├── Mock sunucu
    └── Test paketi

Apidog'un Spesifikasyon-Önce Modu, bu iş akışı için tasarlanmıştır. OpenAPI dosyasını Apidog'a bağlarsınız; platform aynı dosyadan belgeleri, mock'ları ve testleri üretir. YAML değiştiğinde alt çıktılar da aynı kaynaktan güncellenir.

Bu modelde kayacak ayrı bir Postman koleksiyonu yoktur.

GitHub tabanlı ekipler için OpenAPI spesifikasyonunu GitHub ile senkronize etme iş akışı, spesifikasyonun GitHub'da nasıl tutulacağını ve Apidog ile nasıl uyumlu kalacağını gösterir.

POC sırasında özellikle şunları kontrol edin:

• Mevcut OpenAPI şema karmaşıklığınız test üretiminde nasıl ele alınıyor?
• Veri odaklı test senaryoları ihtiyacınızı karşılıyor mu?
• Rapor görünürlüğü ve izinler kuruluş erişim modelinizle uyumlu mu?
• Mock yanıtları frontend geliştirme akışınıza yeterli mi?

Mocking de aynı modelin parçasıdır. Mock, testlerle aynı spesifikasyondan türediğinde frontend geliştiricisi testlerin doğruladığı sözleşmeyle tutarlı yanıtlar alır. Detaylar için API mocking kullanım durumları bölümüne bakabilirsiniz.

Geçiş yolu: Swagger + Postman'dan tek spesifikasyona

Bu geçişi big-bang olarak yapmak zorunda değilsiniz. Daha güvenli yol kademeli ilerlemektir.

1. Mevcut farkı ölçün

Önce openapi.yaml ile Postman koleksiyonunu karşılaştırın.

Kontrol etmeniz gerekenler:

• Koleksiyonda olup spesifikasyonda olmayan endpoint'ler
• Spesifikasyonda olup koleksiyonda test edilmeyen endpoint'ler
• Farklı HTTP metodları
• Farklı path parametreleri
• Farklı request body alanları
• Farklı response şemaları

Basit bir başlangıç için endpoint listesini çıkarabilirsiniz:

# OpenAPI path listesini görmek için örnek
yq '.paths | keys' openapi.yaml

Postman koleksiyonunu JSON olarak dışa aktarıp endpoint'leri ayrı listeleyerek manuel karşılaştırma yapabilirsiniz.

2. Spesifikasyonu gerçek API ile uzlaştırın

openapi.yaml, ilk tasarlandığı API'yi değil, bugün çalışan API'yi tanımlamalıdır.

Bu adımda:

• Eksik endpoint'leri ekleyin.
• Artık kullanılmayan endpoint'leri kaldırın veya deprecated olarak işaretleyin.
• Request body şemalarını güncelleyin.
• Response örneklerini gerçek davranışla uyumlu hale getirin.
• Zorunlu alanları gerçek doğrulama kurallarıyla eşleştirin.

3. Spesifikasyonu Apidog'a aktarın

Temizlenmiş openapi.yaml dosyasını Apidog'a aktarın. Apidog'un spesifikasyon yapısından başlangıç test paketini oluşturmasına izin verin.

Bu noktada hedef, mevcut Postman koleksiyonunu hemen silmek değildir. Önce aynı API'yi iki tarafta da çalıştırıp sonuçları karşılaştırın.

4. Bir sprint paralel çalıştırın

Bir sprint boyunca:

• Mevcut Postman koleksiyonunu çalıştırın.
• Apidog tarafında spesifikasyondan türetilen testleri çalıştırın.
• Farklı sonuç veren endpoint'leri inceleyin.
• Farkın kaynağını belirleyin: API mi yanlış, spesifikasyon mu yanlış, eski test mi yanlış?

5. Postman koleksiyonunu arşivleyin

Sonuçlar hizalandığında:

• Postman koleksiyonunu regresyon kaynağı olarak kullanmayı bırakın.
• Koleksiyonu salt okunur arşivleyin.
• Git'teki openapi.yaml dosyasını tek sözleşme kaynağı yapın.
• Test, mock ve dokümantasyonu spesifikasyondan türetin.

Spesifikasyondan ilk test koleksiyonunu üretme adımları için OpenAPI spesifikasyonlarından test koleksiyonları oluşturma kılavuzuna bakabilirsiniz.

Karşılaştırma: Çift bakım vs. kaynak olarak spesifikasyon

Boyut	Swagger + Postman	OpenAPI odaklı model
Kayma riski	Yüksek; iki yapıt ayrı güncellenir	Düşük; tek yapıt, türetilmiş çıktılar
Test kapsamı doğruluğu	Manuel senkronizasyona bağlı	Spesifikasyon değişikliklerini izler
Yeni geliştirici onboarding	İki araç ve iki sözleşme kopyası	Tek spesifikasyon
CI/CD entegrasyonu	Koleksiyon ayrıca dışa aktarılır ve sürümlenir	CI Git'teki spesifikasyonu okuyabilir
Mock tutarlılığı	Mock ayrıca yönetilir	Mock testlerle aynı spesifikasyondan türetilir
Şema değişikliği maliyeti	Spesifikasyonu, koleksiyonu ve mock'u ayrı güncelle	Spesifikasyonu bir kez güncelle

Bu, Postman'ın kötü bir araç olduğu anlamına gelmez. Postman koleksiyon tabanlı testlerde güçlüdür. Sorun, koleksiyonu türetilmiş bir çıktı yerine ikinci bir sözleşme kaynağı olarak kullanmaktır.

Sıkça Sorulan Sorular

Swagger'ı Postman'a aktarmak neden kaymayı çözmez?

Çünkü aktarım anlık bir kopya oluşturur. Aktarımdan sonra openapi.yaml ve Postman koleksiyonu bağımsız hale gelir. YAML'deki sonraki değişiklik koleksiyona otomatik yayılmaz. Her değişiklikte yeniden aktarım veya manuel koleksiyon düzenleme gerekir.

Spesifikasyon-önce modele geçerken Postman'ı keşif testleri için kullanabilir miyim?

Evet. Spesifikasyon-önce yaklaşım, tek seferlik keşif çağrılarını engellemez. Postman'ı manuel denemeler için kullanabilirsiniz. Önemli olan, keşif koleksiyonunu sözleşme doğrulamasının gerçeklik kaynağı olarak kabul etmemektir.

Spesifikasyonun gerçek API'den saptığını nasıl anlarım?

Bunun için sözleşme test katmanı gerekir. API sunucusu test zamanında gelen istekleri ve dönen yanıtları OpenAPI spesifikasyonuna göre doğrulamalıdır.

Spectral gibi araçlar spesifikasyonun iç tutarlılığını kontrol eder. Ancak gerçek uygulama davranışının spesifikasyondan sapıp sapmadığını görmek için çalışma zamanı doğrulaması gerekir.

Apidog Postman'ı tamamen değiştirir mi?

Bu ekibinizin iş akışına bağlıdır. Apidog tasarım, mocking, test ve dokümantasyonu tek çalışma alanında yönetir. Postman'ı ağırlıklı olarak sözleşme testleri ve regresyon paketleri için kullanıyorsanız Apidog bu alanı kapsayabilir.

Ekibiniz CI'da Postman collection runner kullanıyorsa veya kapsamlı koleksiyon script'lerine sahipse, Postman ile test etme iş akışı spesifikasyon-önce tasarımın yanında değerlendirilebilir. En doğru karar için bir deneme sprint'i çalıştırın.

openapi.yaml dosyam zaten güncel değilse ne yapmalıyım?

Önce spesifikasyonu uzlaştırmanız gerekir. Kestirme yol yoktur.

Yapılacak iş:

1. Mevcut API davranışını çıkarın.
2. openapi.yaml ile karşılaştırın.
3. YAML'yi gerçek davranışı yansıtacak şekilde güncelleyin.
4. Bundan sonra YAML'yi ana sözleşme kaynağı yapın.
5. Test, mock ve dokümantasyonu bu kaynaktan türetin.

Sonuç

Swagger belgeleri ve Postman koleksiyonları, aralarında bağlayıcı bir mekanizma olmayan iki ayrı yapıt oldukları için kayar. Bu bir ekip disiplini problemi değil, çift bakım modelinin doğal sonucudur.

Daha sağlam model şudur:

Git'te tek OpenAPI dosyası
        ↓
Dokümantasyon + Mock + Test

Apidog'u indirin, mevcut OpenAPI spesifikasyonunuzu içe aktarın ve tek dosyadan belgelerin, mock'ların ve testlerin nasıl üretildiğini deneyin. Spesifikasyon-Önce Modu'nu değerlendiriyorsanız güncel kapsam ve erişim bilgileri için Apidog Spesifikasyon-Önce Modu sayfasına bakın.