Postman mı Swagger mı: API Tasarımı ile API Testi Arasındaki Sınır

Aynı API, farklı aşamalar

Postman ve Swagger çoğu zaman rakip gibi karşılaştırılır, ama API yaşam döngüsünün farklı aşamalarına odaklanırlar. Swagger, OpenAPI Spesifikasyonu etrafında kurulmuş bir araç ailesidir. Swagger'ın resmî belgelerine göre OpenAPI Spesifikasyonu'nun eski adı Swagger Spesifikasyonu'dur; bugün Swagger adı bu formatla çalışan araçları anlatır. Swagger Editor ile API tanımı yazılır ve anında doğrulanır, Swagger UI bu tanımdan etkileşimli dokümantasyon üretir, Swagger Codegen tanımdan sunucu iskeleti ve istemci kütüphanesi üretir.

Postman ise bir API istemcisi ve test platformu olarak başladı. Çalışan bir API'ye istek gönderir, yanıtı inceler, istekleri koleksiyonlarda düzenler, ortam değişkenleriyle aynı testi farklı sunucularda çalıştırır, test betikleriyle yanıtı doğrular ve sahte sunucu (mock server) ile henüz yazılmamış bir API'yi taklit eder. Kısacası Swagger "API nasıl olmalı" sorusunu, Postman "API gerçekten böyle mi davranıyor" sorusunu merkeze alır.

Ölçüt ölçüt farklar

• Temel birim: Postman / koleksiyon, yani kaydedilmiş istekler, değişkenler ve test betikleri. Swagger / OpenAPI tanım dosyası, yani uç noktalar, parametreler, şemalar ve yanıt tipleri.
• Ana iş: Postman / API'yi çağırmak, keşfetmek, test etmek ve testleri otomatikleştirmek. Swagger / API sözleşmesini tasarlamak, doğrulamak, belgelemek ve koddan önce üzerinde anlaşmak.
• Dokümantasyon: Postman / koleksiyondan yayımlanan belge, örnek istek ve yanıtlarla. Swagger / Swagger UI ile tanım dosyasından otomatik üretilen, tarayıcıdan denenebilir referans belge.
• Kod üretimi: Postman / tek tek istekler için çeşitli dillerde istek kodu parçası verir. Swagger / Codegen ile tanımdan sunucu iskeleti ve istemci kütüphanesi üretir.
• Test: Postman / istek öncesi ve sonrası JavaScript betikleri, koleksiyon koşucusu, komut satırı ile CI hattında çalıştırma. Swagger / tek başına bir test aracı değildir; Swagger UI'daki deneme özelliği el ile tek istek atmaya yarar.
• Lisans ve dağıtım: Postman / masaüstü ve web uygulaması, ekip özellikleri ücretli planlarda. Swagger / Editor, UI ve Codegen açık kaynak; ekip ve kurum özellikleri ticari Swagger planlarında.

Güncel plan kapsamları ve ücretler her iki ürünün resmî sitesinde yayımlanır ve sık değişir.

Sözleşmeden teste örnek akış

Örneğin bir ekip yeni bir sipariş API'si geliştiriyor ve önce sözleşme üzerinde anlaşmak istiyor. Akış şöyle ilerler: • Tasarım: Backend geliştiricisi Swagger Editor'da sipariş oluşturma ve sorgulama uç noktalarını, istek gövdesinin şemasını ve hata yanıtlarını tanımlar. Editor, şema hatalarını yazarken gösterir. • Gözden geçirme: Tanım dosyası depoya konur, Swagger UI ile mobil ve web ekiplerine paylaşılır. Alan adları ve zorunlu alanlar kod yazılmadan tartışılır. • Paralel geliştirme: Tanımdan bir mock sunucu çıkarılır; mobil ekip gerçek servis hazır olmadan bu sahte yanıtlarla çalışır. • Test: QA mühendisi tanım dosyasını Postman'e aktarır, oluşan koleksiyona ortam değişkenleri ve doğrulama betikleri ekler. • Otomasyon: Koleksiyon, CI hattında komut satırından her derlemede çalışır; sözleşmeden sapan bir yanıt hattı durdurur.

Postman tarafında tipik bir doğrulama betiği şöyle görünür:

pm.test("Sipariş yanıtı geçerli", function () { pm.response.to.be.ok; const body = pm.response.json(); pm.expect(body).to.have.property("orderId"); });

Bu akışta Swagger sözleşmenin kaynağıdır, Postman ise uygulamanın bu sözleşmeye uyup uymadığını sürekli kontrol eden araçtır.

Örtüşen alanlar ve karışıklığın kaynağı

İki ürün de zamanla birbirinin alanına girdi, karışıklığın asıl nedeni budur. Postman OpenAPI tanımlarını içe aktarabilir, tanımdan koleksiyon üretebilir ve resmî belgelerinde API yapısını tasarlamak için ayrı bir tasarım alanı tanımlar. Swagger tarafında ise Swagger UI'daki deneme düğmesi gerçek bir istek gönderir; ticari Swagger planları da mock ve ekip iş birliği özellikleri sunar.

Yine de odak farkı sürer. Postman'de tasarım özelliği bir test ve iş birliği platformunun parçasıdır; Swagger'da istek atma özelliği dokümantasyonun parçasıdır. Ekipler araç seçerken "hangisi her şeyi yapıyor" sorusundan çok "API'nin doğruluk kaynağı nerede duracak" sorusunu yanıtlamalıdır. Sözleşme öncelikli çalışan ekiplerde bu kaynak genellikle depodaki OpenAPI dosyasıdır; Postman koleksiyonu bu dosyadan türetilir.

Hangi durumda hangisi?

Swagger araçlarını öne alın: • API henüz yazılmadıysa ve önce ekipler arası sözleşme kurmak istiyorsanız • Dış geliştiricilere açık, tanım dosyasından otomatik güncellenen referans dokümantasyon gerekiyorsa • Aynı tanımdan farklı dillerde istemci kütüphanesi ya da sunucu iskeleti üretmek istiyorsanız

Postman'i öne alın: • Mevcut bir API'yi keşfetmek, hata ayıklamak ya da üçüncü taraf bir API'yi denemek istiyorsanız • Uçtan uca senaryolar, kimlik doğrulama zincirleri ve ortamlar arası testler yazacaksanız • API testlerini CI hattına bağlamak ve ekip içinde paylaşılan koleksiyonlarla çalışmak istiyorsanız

Olgun ekiplerin çoğunda soru "hangisi" değil "hangisi nerede" sorusudur: sözleşme Swagger ile yazılır ve yayımlanır, davranış Postman ile doğrulanır.

Sık yapılan hatalar

En sık hata, OpenAPI tanımını bir kez üretip unutmaktır. Kod değişir, tanım güncellenmez ve Swagger UI'daki dokümantasyon gerçeği yansıtmaz hale gelir. Bunu önlemek için tanım ya koddan otomatik üretilmeli ya da sözleşme testleriyle kodun tanıma uyduğu CI hattında doğrulanmalıdır.

Postman tarafındaki yaygın hata ise koleksiyonu kişisel bir not defteri gibi kullanmaktır: sabit yazılmış adresler, betiklerde açık bırakılmış erişim anahtarları, sırasına bağımlı testler. Ortam değişkenleri, gizli değerlerin ayrı tutulması ve her testin kendi verisini hazırlaması bu sorunları azaltır. Postman'in resmî belgeleri, koleksiyonları komut satırından çalıştırmak için Newman yerine artık Postman CLI'yi önerir; yeni kurulan CI hatlarında bu tercih dikkate alınmalıdır.

Mindset programlarında iki araç

Postman ile API Testi eğitimi, HTTP temelleri, koleksiyon ve ortam yönetimi, test betikleriyle doğrulama, kimlik doğrulama ve güvenlik testi, mock server ve Newman ile CI/CD entegrasyonu başlıklarıyla test tarafını işler. QA ve backend ekipleri için uygundur.

OpenAPI ile Sözleşme Öncelikli API Tasarımı eğitimi ise şema modelleme, hata sözleşmesi ve güvenlik tanımları, taklit sunucu ve kod üretimi, sözleşme testleri ve CI entegrasyonu üzerinden tasarım tarafına odaklanır. Mobil, web ve backend ekiplerinin aynı sözleşme üzerinde çalıştığı kurumlarda iki program birlikte, ortak bir API sürecinin parçaları olarak ele alınabilir.