Stoplight + Postman vs Apidog: API Tasarımı, Dokümantasyonu ve Testi için Tek Platform

Ekibiniz OpenAPI tasarımı ve belgeleri için Stoplight, koleksiyonlar ve testler için Postman kullanıyorsa sorun tanıdıktır: API spesifikasyonu ve testler zamanla ayrışır. Stoplight Postman alternatifi arıyorsanız, muhtemelen aynı API sözleşmesi için iki araç, iki fatura ve iki doğruluk kaynağı yönetmekten yoruldunuz. Apidog, OpenAPI spesifikasyonunu tasarım, dokümantasyon, mock sunucu ve otomatik testler için tek doğruluk kaynağı olarak kullanır.

Apidog'u bugün deneyin

Bu yazı, Stoplight ve Postman’ın güçlü olduğu alanları, iki araçlı kurulumun nerede sürtünme yarattığını ve Apidog’da birleşmenin ekibiniz için ne zaman mantıklı olduğunu uygulama odaklı şekilde inceler. Bu genel bir “alternatifler listesi” değil; mevcut API geliştirme yığınını değiştirme değerlendirmesidir. Spesifikasyon öncelikli yaklaşımı daha derin incelemek için Spesifikasyon Öncelikli API Geliştirme Nedir? yazısına bakabilirsiniz.

İki araç sorunu

Stoplight ve Postman API yaşam döngüsünün farklı parçalarını iyi çözer:

• Stoplight: görsel OpenAPI düzenleyici, Git destekli spesifikasyon deposu, otomatik referans dokümantasyonu.
• Postman: koleksiyon çalıştırıcı, ortam değişkenleri, pre-request script’ler, test panosu ve CI için Newman.

Birlikte tasarımdan teste kadar geniş kapsama sağlarlar. Ancak ayrı çalıştıklarında üç pratik sorun oluşur.

1. Spesifikasyon-test sapması

OpenAPI spesifikasyonunuz Stoplight ile Git deposunda yaşar. Postman koleksiyonunuz Postman bulutunda yaşar.

Bir geliştirici spesifikasyondaki request body şemasını değiştirirse Postman testleri otomatik güncellenmez. QA ekibi eski koleksiyonu yeni endpoint’e karşı çalıştırdığında test başarısız olur. Bu ürün hatası değil, araçlar arasındaki senkronizasyon boşluğudur.

2. Tekrarlanan bakım

Şu bilgiler genellikle iki kez tanımlanır:

• Path parametreleri
• Base URL’ler
• Ortamlar: staging, production, EU region vb.
• Kimlik doğrulama şemaları
• Response şemaları

Tipik iş akışı şöyle görünür:

1. OpenAPI spesifikasyonunu oluştur.
2. Swagger veya Stoplight Docs’ta görüntüle.
3. Test etmek için Postman’a aktar.
4. Spesifikasyon değişince Postman koleksiyonunu manuel güncelle.
5. Ortam değişikliklerini iki yerde tekrar uygula.

Bu “aktar ve yamala” döngüsü büyüyen ekiplerde hızla maliyet üretir.

3. İki fatura, tek API sözleşmesi

Stoplight platform katmanı ve dokümantasyonu kapsar. Postman koleksiyonlar, test çalıştırmaları ve monitoring tarafını kapsar.

Kuruluşunuz ikisini birlikte kullanıyorsa, tek API sözleşmesini yönetmek için iki ayrı platform maliyeti oluşur.

Stoplight neyi iyi yapar?

Stoplight’ın en güçlü tarafı görsel OpenAPI düzenleyicisidir. YAML/JSON yazarken doğrulama yapar, Spectral ile stil kuralları uygular ve teknik olmayan paydaşlar için okunabilir bir form görünümü sağlar.

Git entegrasyonu Git-native çalışır:

• Her kayıt GitHub veya GitLab deposuna commit olur.
• Branch protection kuralları normal şekilde uygulanır.
• OpenAPI dosyaları repository içinde kalır.

Stoplight Docs da güçlüdür:

• Referans dokümantasyonu otomatik oluşturur.
• Özel domain ile yayınlanabilir.
• toc.json ile içerik yapısı kontrol edilebilir.
• Dahili endpoint’ler işaretlenebilir.
• “Try it” API explorer gömülebilir.

Ancak Stoplight’ın sınırı yürütme tarafındadır. Yerleşik test runner, sözleşme doğrulama motoru veya CI test raporlama akışı sağlamaz. Spesifikasyonu tasarladıktan sonra test tarafı başka bir araca devredilir.

Postman neyi iyi yapar?

Postman’ın koleksiyon modeli çoğu geliştiriciye tanıdıktır:

• Koleksiyonlar istekleri gruplandırır.
• Ortamlar değişken ikamesi sağlar.
• Test sekmesi pm.test() ile JavaScript doğrulamalarını çalıştırır.
• Collection Runner ve Newman CLI testleri CI pipeline’larında çalıştırabilir.

Örnek Postman testi:

pm.test("Durum 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Yanıtta orderId var", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("orderId");
});

Postman monitoring, canlı endpoint’lere karşı planlı koleksiyon çalıştırmaları yapar ve hata durumunda uyarı verebilir. Üretim uptime kontrolleri yapan ekipler için bu pratik bir özelliktir.

Zayıf nokta ise spesifikasyondan kopuk çalışmasıdır. OpenAPI’den içe aktarılan koleksiyonlar varsayılan olarak ayrışır. Koleksiyonu spesifikasyonla senkron tutmak için ya manuel yeniden içe aktarma ya da özel senkronizasyon script’i gerekir.

Platform karşılaştırması: Stoplight vs Postman vs Apidog

Aşağıdaki tablo, temel API yaşam döngüsü yeteneklerini üç araç arasında karşılaştırır.

• Yerel: Özellik temel iş akışının birinci sınıf parçasıdır.
• Kısmi: Özellik vardır ancak manuel adım veya workaround gerektirir.
• Hayır: Araç bu yeteneği kapsamaz.

Yetenek	Stoplight	Postman	Apidog
Görsel OpenAPI düzenleyici	Yerel	Kısmi	Yerel
Spectral / lint kuralları	Yerel	Hayır	Yerel
Git depo senkronizasyonu: GitHub, GitLab	Yerel	Hayır	Yerel: Spec-First Modu, beta
Branch tabanlı spesifikasyon iş akışları	Yerel	Hayır	Yerel
Otomatik referans dokümantasyonu	Yerel	Kısmi	Yerel
Etkileşimli dokümantasyon: try it	Yerel	Hayır	Yerel
Özel doküman erişim kontrolü	Yerel	Hayır	Deneme sürümünde doğrulamaya değer
Spesifikasyondan mock sunucu	Kısmi: Prism	Kısmi	Yerel
İstek koleksiyonu çalıştırıcısı	Hayır	Yerel	Yerel
JavaScript test script’leri	Hayır	Yerel	Yerel
Görsel doğrulama düzenleyici	Hayır	Hayır	Yerel
Ortam değişkeni yönetimi	Hayır	Yerel	Yerel
CI/CD entegrasyonu: Newman / CLI	Hayır	Yerel	Yerel
Spesifikasyondan sözleşme testi	Hayır	Hayır	Yerel
Çapraz proje şema yeniden kullanımı	Kısmi	Hayır	Deneme sürümünde doğrulamaya değer
SSO / SCIM	Evet: Enterprise	Evet: Enterprise	Gereksinimlerinize göre kontrol edin
Denetim günlükleri	Evet	Evet	Gereksinimlerinize göre kontrol edin

“Deneme sürümünde doğrulamaya değer” olan alanları gerçek ekip yapınızla test edin. Özellikle çapraz proje bileşen yeniden kullanımı ve rapor görünürlüğü izinleri, demo verisiyle değil gerçek workspace yapısıyla değerlendirilmelidir.

Apidog’un Spec-First Modu neyi değiştirir?

Apidog’un Spesifikasyon Öncelikli Modu, mevcut GitHub veya GitLab deponuzu yetkili OpenAPI kaynağı olarak bağlar.

Tek seferlik OpenAPI import yerine çalışma alanı Git commit’leriyle senkron kalır. Bir geliştirici path parametresini değiştiren PR’ı merge ettiğinde Apidog değişikliği alır. Mock sunucular, dokümantasyon ve test doğrulamaları aynı yeni şemaya göre güncellenir.

Stoplight + Postman kullanan ekip için pratik akış şöyle olur:

1. Mevcut OpenAPI repository’nizi koruyun.
2. Apidog’da Spec-First Mode ile GitHub veya GitLab bağlantısı kurun.
3. Spesifikasyondan mock sunucu üretin.
4. Frontend ekibine backend hazır olmadan gerçekçi response’lar sağlayın.
5. Spesifikasyon şemasından test senaryoları oluşturun.
6. Gerekirse ek doğrulamalar ekleyin.
7. Testleri CI’da Apidog CLI ile çalıştırın.
8. Dokümantasyonu aynı spesifikasyondan otomatik güncel tutun.

Kurulum detayları için Spesifikasyon Öncelikli Mod kılavuzu kullanılabilir. Spec-first ve design-first yaklaşım farkları için Spesifikasyon Öncelikli mi Yoksa Tasarım Öncelikli mi: Hangi Apidog Modunu Kullanmalısınız? yazısı da yararlıdır.

Çalışan örnek: OpenAPI’den sözleşme testi

Aşağıdaki endpoint’i düşünün:

GET /orders/{orderId}

Postman’da bu endpoint için testleri manuel yazarsınız:

// Postman test sekmesi: manuel yazılır ve spesifikasyondan ayrı yaşar
pm.test("Durum 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Yanıtın orderId'si var", function () {
  const json = pm.response.json();
  pm.expect(json).to.have.property("orderId");
  pm.expect(json.orderId).to.be.a("string");
});

Bu test, OpenAPI spesifikasyonunda zaten bulunan bilgiyi tekrar eder. Birisi şemaya yeni bir required alan eklerse ancak Postman koleksiyonunu güncellemezse testler eksik kalır.

Spec-First yaklaşımda doğrulamanın kaynağı OpenAPI dosyasıdır:

# Git deponuzdaki OpenAPI parçacığı: örn. openapi/orders.yaml
paths:
  /orders/{orderId}:
    get:
      summary: Kimliğe göre sipariş al
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Sipariş bulundu
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

components:
  schemas:
    Order:
      type: object
      required:
        - orderId
        - status
        - createdAt
      properties:
        orderId:
          type: string
        status:
          type: string
          enum: [pending, processing, shipped, delivered]
        createdAt:
          type: string
          format: date-time

Bu spesifikasyon senkronize edildiğinde Apidog, 200 response şemasını test senaryosunda sözleşme doğrulaması olarak kullanır.

Pratik sonuç:

• Response içinde status eksikse test başarısız olur.
• createdAt geçerli date-time formatında değilse doğrulama yakalar.
• status enum dışı bir değer döndürürse sözleşme testi hata verir.
• Manuel Postman testini her şema değişikliğinde güncellemeniz gerekmez.

OpenAPI ve Git ilişkisini yapılandırmak için Bir OpenAPI Spesifikasyonunu Git ile Nasıl Sürüm Kontrol Edersiniz? yazısına bakabilirsiniz.

Geçişten önce doğrulamanız gerekenler

Kurumsal ölçekte platform konsolidasyonu yapmadan önce aşağıdaki alanları gerçek verinizle test edin.

Rapor görünürlüğü izinleri

CI test raporlarını belirli ekipler veya projelerle sınırlayabiliyor musunuz?

Kontrol listesi:

• Proje bazlı rapor erişimi
• Takım bazlı yetkilendirme
• Paylaşılan workspace’lerde görünürlük sınırları
• Harici paydaş erişimi

SSO ve SCIM sağlama

Apidog SSO destekler. Ancak SCIM otomatik kullanıcı sağlama, grup senkronizasyonu ve kullanıcı kaldırma davranışını kimlik sağlayıcınıza karşı test edin.

Referans olarak SCIM RFC kullanılabilir.

Test edilmesi gerekenler:

• Yeni kullanıcı otomatik oluşturuluyor mu?
• Grup değişiklikleri doğru yansıyor mu?
• Kullanıcı devre dışı bırakılınca erişim kaldırılıyor mu?
• Rol eşlemeleri beklediğiniz gibi çalışıyor mu?

Çapraz proje şema yeniden kullanımı

Birden fazla API projesinde ortak $ref şemalarınız varsa Apidog’un workspace modelini test edin.

Örnek durumlar:

$ref: "../shared/schemas/ErrorResponse.yaml"

veya:

$ref: "https://example.com/schemas/customer.yaml#/Customer"

Doğrulamanız gerekenler:

• Dosyalar arası $ref çözümlemesi
• Mono-repo yapıları
• Çoklu repository yapıları
• Paylaşılan component güncellemelerinin projelere etkisi

Denetim günlükleri

Uyumluluk gereksinimleriniz varsa şu bilgileri kontrol edin:

• Spesifikasyon değişiklikleri loglanıyor mu?
• API erişimleri izleniyor mu?
• Log formatı dış sistemlere aktarılabilir mi?
• Saklama süresi gereksinimlerinizi karşılıyor mu?

Bu maddeler Apidog’dan kaçınmak için değil, herhangi bir platform geçişinde doğru riskleri erken görmek için kullanılmalıdır.

İki aracı ne zaman tutmalı?

Tek platforma geçmek, spesifikasyon-test sapması ve çift bakım maliyeti geçiş maliyetinden yüksek olduğunda mantıklıdır. Ancak bazı durumlarda Stoplight + Postman yığınını korumak daha doğru olabilir.

İki araçlı yapı şu durumlarda mantıklı kalabilir:

• Stoplight Docs dağıtımınız teknik yazarlar tarafından yönetilen özel toc.json yapısıyla derin özelleştirilmiştir.
• Postman koleksiyonunuzda yüzlerce pre-request script ve dinamik değişken zinciri vardır.
• Üretim uptime kontrolleri için Postman monitors kullanıyorsunuzdur.
• Newman JSON çıktısı etrafında özel dashboard veya raporlama entegrasyonu kurmuşsunuzdur.
• Geçiş için ekibin yeniden eğitim maliyeti kısa vadede çok yüksektir.

Özellikle Postman tarafında daha geniş alternatifleri değerlendirmek isterseniz API Testi için En İyi Postman Alternatifleri yazısı açık kaynak seçenekleri de kapsar.

Sıkça Sorulan Sorular

Apidog, Stoplight Studio’nun görsel OpenAPI düzenleyicisinin yerini alır mı?

Evet. Apidog, OpenAPI şemaları için görsel düzenleyici, gerçek zamanlı doğrulama ve lint kuralları sağlar.

Ancak ekibiniz repository içindeki özel .spectral.yaml kurallarına güveniyorsa, Apidog’un linting davranışının bu kuralları kapsadığını geçişten önce doğrulayın.

Apidog mevcut GitHub deposuyla yeniden import yapmadan senkronize olabilir mi?

Apidog’un Spec-First Modu, şu anda beta aşamasında, GitHub veya GitLab deposuna bağlanır ve çalışma alanını commit’lerle senkron tutar. Mevcut OpenAPI repository’nizi kaldırmanız gerekmez.

Spesifikasyonu Git’te tutma yaklaşımı için Kod Olarak API Spesifikasyonu yazısına bakabilirsiniz. Ardından bağlantı adımları ve beta sınırlamaları için Apidog dokümantasyonunu kontrol edin.

Apidog CI’da Newman tarzı CLI test çalıştırmalarını destekliyor mu?

Apidog’un kendi CLI aracı vardır. Test senaryolarını çalıştırabilir ve rapor üretebilir.

Mevcut pipeline’ınız şu komutu kullanıyorsa:

newman run collection.json

bunu Apidog CLI eşdeğeriyle değiştirmeniz gerekir. Çıktı formatı farklı olabileceği için Newman JSON çıktısına bağlı dashboard veya raporlama entegrasyonlarını ayrıca değerlendirmeniz gerekir.

Postman pre-request script’leri ve dinamik değişkenleri ne olacak?

Apidog pre-request script’leri ve dinamik değişkenleri destekler. Mock data üreticileri de kullanılabilir.

Ancak Postman koleksiyonunuz yoğun şekilde şu API’lere bağlıysa:

pm.variables.set("token", token);
pm.environment.get("baseUrl");

script’lerin taşınması gerekir. Mantık çoğunlukla aktarılabilir, fakat sözdizimi ve çalışma bağlamı bazı yerlerde farklılık gösterebilir.

Apidog’un Spec-First Modu üretim için hazır mı?

Spec-First Mod şu anda beta aşamasındadır. Temel işlevler çalışır, ancak büyük mono-repo spesifikasyonları, dosyalar arası iç içe $ref çözümlemesi ve CI durum raporlaması gibi uç durumlar için gerçekçi bir proof of concept çalıştırmanız gerekir.

Sonuç

Stoplight ve Postman gerçek problemleri çözer, ancak bunları iki ayrı yerde çözer. Spesifikasyon ve testler farklı araçlarda yaşadığında sapma istisna değil, varsayılan sonuç olur.

Apidog’un Spec-First Modu, tek platforma geçiş için pratik bir yol sunar:

• Git doğruluk kaynağı olarak kalır.
• OpenAPI spesifikasyonu merkezi kaynak olur.
• Dokümantasyon aynı şemadan üretilir.
• Mock sunucular spesifikasyondan oluşturulur.
• Testler ve sözleşme doğrulamaları spesifikasyona bağlı kalır.
• CI raporları aynı API sözleşmesine göre çalışır.

Geçiş kararı vermeden önce özellikle SSO, rapor izinleri, denetim günlükleri ve çapraz proje şema yeniden kullanımı alanlarını proof of concept içinde test edin.

Apidog’un Spec-First Modunu denemek için OpenAPI deponuzu GitHub veya GitLab’dan bağlayabilir, aynı spesifikasyondan canlı dokümantasyon ve mock sunucu oluşturabilirsiniz. Başlamak için Apidog’u indirin veya Spesifikasyon Öncelikli Mod sayfasını ziyaret edin.