Postman koleksiyonları ile OpenAPI belirtimi arasındaki soru, bir ekip birkaç mühendisi aşan bir büyüklüğe ulaştığında her zaman ortaya çıkar. Altı ay önce yazdığınız koleksiyonu açtığınızda, artık üç ekstra zorunlu alanı, iki kullanım dışı parametresi ve sunucunun gerçekten döndürdüğüyle uyuşmayan bir yanıt şekli olan bir uç noktayı tanımladığını görürsünüz. Git'teki OpenAPI belirtimi farklı bir şey söylüyor. Swagger UI'nız başka bir şey söylüyor. Hangisinin doğru olduğundan kimse emin değil.
Bu sapma bir araç hatası değildir. Bu bir iş akışı hatasıdır ve ayrım önemlidir. Postman, istek yürütme, betikleme ve keşif testi için mükemmel bir araçtır. Sorun, ekiplerin koleksiyonu API sözleşmesinin kendisi olarak değil, bu sözleşmeden türetilmiş bir yapıt olarak ele almasıdır.
Koleksiyonlar neden başta sapar?
Postman koleksiyonu, istek odaklı bir yapıdır. Bir istek gönderir, yanıtı gözlemlersiniz ve kaydedersiniz. Zamanla, ekibinizin API hakkında nasıl düşündüğünü yansıtan ön-istek betikleri, değişken ikameleri, test iddiaları ve klasör yapıları eklersiniz, ancak API'nin resmi olarak neyi belirttiğini değil.
OpenAPI belirtiminiz ise aksine, sözleşme odaklı bir yapıdır. Yolları, parametreleri, şemaları ve yanıt türlerini araçların doğrulayabileceği, taklit edebileceği ve kod üretebileceği makine tarafından okunabilir bir formatta beyan eder.
İki yapıt farklı soruları yanıtlar. Koleksiyon "bu uç noktayı bugün nasıl çağırırım?" sorusunu yanıtlar. Belirtim ise "bu API ne yapmalı?" sorusunu yanıtlar. Ekipler her ikisini de bağımsız olarak sürdürdüğünde, kaçınılmaz olarak ayrışırlar. Bir geliştirici bir çekme isteğini birleştirirken belirtimi günceller. Diğeri ise bir testin bozulduğunu fark ettiğinde koleksiyonu günceller. Kimse onları birleştirmez. Birkaç ay içinde aynı API'nin iki kısmen doğru açıklamasına sahip olursunuz ve hangisinin daha güncel olduğunu güvenilir bir şekilde belirlemenin bir yolu kalmaz.
Bu modelin müşteri kanıtları somuttur. Inventis Korea tam da bu sorunu bildirdi: ekipleri bir API oluşturdu, Swagger için bir OpenAPI belirtimi oluşturdu, test için koleksiyonu Postman'e aktardı ve ardından üç temsilin senkronizasyonunu sağlamak için sürekli çaba harcadı. Koleksiyon tam şemayı yansıtmadığı için testler kenar durumları kaçırdı. Belirtim test oluşturmanın girdisi olmadığı için dokümantasyon saptı. Bunlar kenar durumları değildir; bunlar, büyük ölçekli istek odaklı bir iş akışının öngörülebilir sonuçlarıdır.
Temel neden: Postman, bir belirtim deposu olarak tasarlanmamıştır
Postman koleksiyonlarının kendi formatı vardır. Postman koleksiyon şeması, istekleri, betikleri ve klasör hiyerarşilerini tanımlayan tescilli bir JSON yapısıdır. Bu OpenAPI değildir. Postman, OpenAPI'yi içe ve dışa aktarabilir, ancak her iki yönde de dönüşüm kayıplıdır: OpenAPI'den koleksiyona, istekler olarak ifade edilemeyen şema ayrıntılarını düşürür; koleksiyondan OpenAPI'ye, belirtim alanları olarak ifade edilemeyen betikleri ve verileri düşürür.
Bu Postman'a yönelik bir eleştiri değildir. Bu, aracın aslında ne için olduğunun bir açıklamasıdır. Postman, istek merkezli model etrafında inşa edilmiş işbirliği özelliklerine sahip bir istek yürütücüdür. Bunu standart API tanımınız olarak kullanmak, formatın taşımak için tasarlanmadığı bir yapıyı dayatmanızı gerektirir.
Tek bir uç nokta için iki temsili karşılaştırın:
| Özellik | Postman koleksiyonu | OpenAPI belirtimi |
|---|---|---|
| İstek parametreleri | İsteğe bağlı açıklama ile anahtar-değer çiftleri olarak depolanır | Türlü, doğrulanmış, gerekli ve şema alanları ile |
| Yanıt şekli | Kaydedilmiş bir örnek olarak yakalandı (isteğe bağlı) | Yollar arasında $ref yeniden kullanımı ile bir JSON Şeması olarak tanımlanır |
| Hata yanıtları | Her isteğe manuel olarak eklenir | Paylaşılan bileşenler/şemalar ile yanıtlar içinde numaralandırılır |
| Şema yeniden kullanımı | Yok; istekler arasında kopyala-yapıştır | Doğrulayıcılar tarafından uygulanan bileşenler/şemalar için $ref |
| Makine tarafından okunabilir sözleşme | Hayır | Evet; araçlar sunucular, istemciler, sahteler (mock) oluşturabilir |
| Git farklılaştırmaya uygun | Opak kimliklere sahip JSON; anlamlı bir şekilde incelemesi zor | YAML; anlamlı satır düzeyinde farklılıklar |
| Linter ve doğrulama | Yerel formatta değil | Spectral, Redocly CLI ve diğerleri |
Tablo, sapmanın neden gerçekleştiğini gösteriyor: koleksiyon sözleşmeyi tam olarak ifade edemediği için sözleşme başka bir yerde yaşar ve birisi diğerini düzenlemeden birini düzenlediği anda ikisi senkronizasyondan düşer.
Postman ekibi için belirtim odaklı yaklaşım aslında ne anlama geliyor?
Belirtim odaklı yaklaşım "tüm kodu yazmadan önce her şeyi YAML'de tasarlayın" anlamına gelmez. Koleksiyon merkezli bir iş akışından geçiş yapan çoğu ekip için bu, bağımlılığı tersine çevirmek anlamına gelir. Belirtim odaklı metodoloji, OpenAPI belgesini API'nin yetkili tanımı olarak Git'e yerleştirir. Test için kullandığınız koleksiyon da dahil olmak üzere diğer tüm yapıtlar, tersi değil, bu belgeden türetilir.
Pratikte iş akışı şöyle görünür:
- Belirtim Git'e kaydedilir ve PR sürecinin bir parçası olarak gözden geçirilir.
- Testler, mock'lar ve dokümantasyon belirtimden oluşturulur.
- API değiştiğinde, önce belirtim değişir. Aşağı akış yapıtları otomatik olarak veya araçlar aracılığıyla güncellenir.
- Ekibinizin keşif testi için kullandığı koleksiyon belirtimden oluşturulur, böylece her zaman güncel sözleşmeyi yansıtır.
Koleksiyon hala orada. Betikleriniz, veri odaklı testleriniz ve ortam değişkenleriniz hala orada. Fark, koleksiyonun belirtimin aşağı akışında olmasıdır, yukarı akışında değil. Belirtimde yeni bir alan göründüğünde, oluşturulan koleksiyonda da görünür. Bir alan belirtimden kaldırıldığında, oluşturulan istek artık onu içermediği için test başarısız olur. Sapma, altı ay sonra keşfedilen bir hata yerine bir CI hatası haline gelir.
Belirtiminizden koleksiyonları nasıl oluşturursunuz?
Bir OpenAPI belirtiminden Postman uyumlu bir koleksiyon türetmenin birkaç yolu vardır. İşte Redocly CLI ile çalışan bir yol:
# Redocly CLI'yi yükleyin
npm install -g @redocly/cli
# Önce belirtimi doğrulayın
redocly lint openapi/petstore.yaml
# Belirtimi paketleyin ( $ref zincirlerini çözümleyin)
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
# openapi-to-postmanv2 kütüphanesini kullanarak Postman koleksiyonu v2.1'e 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'udur. Bunu Postman'e aktarır veya Newman'da ya da Postman CLI'da temel koleksiyon olarak kullanırsınız. Ön-istek betikleriniz ve ortam değişkenleriniz bağımsız olarak sürdürdüğünüz ayrı dosyalar olarak kalır; güncellenmiş bir belirtimden koleksiyonu yeniden oluşturduğunuzda bunların üzerine yazılmaz.
Koleksiyonun testler çalışmadan önce her zaman belirtimden yeniden oluşturulması için bunu CI'ye bağlayabilirsiniz:
# .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: |
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
openapi2postmanv2 \
--spec dist/petstore-bundled.yaml \
--output dist/petstore-collection.json
- 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 modelle birlikte, belirtim her test çalıştırmasının girdisidir. Bir testi bozan bir belirtim değişikliği, belirtimi değiştiren aynı PR'da yakalanır.
Apidog bu iş akışına nasıl uyuyor?
Apidog'un değeri, Postman'i bir istek yürütücü olarak değiştirmesi değildir. Değeri, OpenAPI belirtimini ekibinizin çalıştığı diğer tüm yapıtlarla manuel dönüştürme adımı olmadan bağlamasıdır. Git'teki belirtim gerçeğin kaynağı olarak kalır; Apidog, bunun üzerinde işbirliği ve yürütme katmanıdır.
Apidog'un Belirtim Odaklı Modu (şu anda beta aşamasında) bir OpenAPI belirtimini bir Git deposundan doğrudan bir Apidog çalışma alanına senkronize etmenize olanak tanır. Bu senkronize edilmiş belirtimden, Git'teki belirtim değiştiğinde otomatik olarak güncellenen otomatik oluşturulmuş mock'lar, etkileşimli dokümantasyon ve test senaryoları elde edersiniz. Belirtimin yanında ayrı bir koleksiyon sürdürmezsiniz; belirtim, Apidog'un ne gösterdiğini ve ne yürüttüğünü belirler.
Bu, STC Group ve Dünya Ekonomik Forumu'nun açıkladığı gibi deneyim yaşayan ekipler için önemlidir: test için Postman'i, belirtim oluşturma için ayrı bir dokümantasyon aracını ve ön uç geliştirme için bir mock sunucusunu sürdürmek, hepsi aynı API sözleşmesini yansıtması gereken üç sistem. Belirtim değiştiğinde, onu tek bir yerde güncellersiniz ve üç yüzey de güncellenir. Apidog'un çalışma alanı izinleri ve SSO ayrıntılarının, özellikle DHL dağıtımında (100+ kullanıcı) açıklanan gibi büyük ekipler için belirli erişim kontrolü gereksinimlerinizi karşılayıp karşılamadığını bir deneme sırasında doğrulamaya değer. Bunlar, bir konsept kanıtı için anlamlı değerlendirme sorularıdır.
Geçiş yolu için, mevcut Postman koleksiyonlarınızı bir başlangıç noktası olarak Apidog'a dönüştürebilir ve ardından belirtimi ileriye dönük olarak standart belge haline getirebilirsiniz. Mekanik içe aktarma adımı, bağlantılı kılavuzda ayrıntılı olarak açıklanmıştır.
Belirtimi Git iş akışınızda kod olarak ele alma
API belirtimi-kod olarak yaklaşımı, OpenAPI belgesinin uygulama koduyla aynı muameleyi görmesi anlamına gelir: çekme istekleri, kod incelemesi, CI'da linting ve sürüm sınırlarında sürüm etiketleri. Çoğu ekip bunun için zaten altyapıya sahip olduğunu fark eder; eksik adım bunu belirtim dosyasına uygulamaktır.
Yardımcı olan birkaç uygulama:
- Belirtimi, ayrı bir "belgeler" deposunda değil, tanımladığı hizmetle aynı depoda saklayın. Bu, belirtim değişikliklerinin kod değişiklikleriyle aynı PR'da gerçekleşmesini sağlar.
- CI boru hattınıza bir Spectral lint adımı ekleyin. Spectral, belirtimi OpenAPI belirtimine ve ekibinizin tanımladığı tüm özel kurallara göre doğrular. Bozuk şema referansları, eksik açıklamalar ve tutarsız adlandırma, inceleme yorumları değil, CI hataları haline gelir.
- Bozucu değişiklikler için dallanmaya dayalı belirtim geliştirme kullanın, uygulama kodunu dallandığınız gibi. Apidog çalışma alanları belirtim üzerinde dallanmayı destekler, böylece farklı ekipler bir bozan değişiklik inceleme aşamasındayken kararlı bir dalla çalışabilir.
- Aşağı akış tüketici depolarında belirtim sürümlerini sabitleyin. Hizmet B, sözleşme testleri için hizmet A'nın belirtimine bağımlı olduğunda, ana dalın HEAD'ine değil, belirli bir sürüm etiketine başvurmalıdır.
Bu yaklaşım, yeni bir proje için adım adım kurulum istiyorsanız Git-yerel API iş akışı kılavuzunda derinlemesine ele alınmıştır.
Sıkça Sorulan Sorular
Postman'i tamamen kullanmayı bırakmak zorunda mıyım?
Hayır. Metodoloji değişikliği, araç değişimi hakkında değil, bağımlılık yönü hakkındadır. Postman'i keşif testleri ve betikleme için kullanmaya devam edebilirsiniz. Fark, koleksiyonunuzun ayrı bir yapıt olarak sürdürülmesi yerine, her test çalıştırmasından önce belirtimden oluşturulmasıdır. Ekibiniz keşif çalışmaları için Postman'in UI'sini tercih ediyorsa, bu tercih belirtim odaklı bir iş akışıyla uyumludur.
Mevcut Postman betiklerimize ve ortam değişkenlerimize ne olur?
Ön-istek betikleriniz, test betikleriniz ve ortam değişkeni tanımlarınız oluşturulan koleksiyonun bir parçası değildir. Bunlar, bağımsız olarak sürdürdüğünüz ayrı dosyalardır. Koleksiyonu güncellenmiş bir belirtimden yeniden oluşturduğunuzda, betikler üzerine yazılmaz. Yapısal katman (istek tanımları) her zaman belirtimden türetilirken, davranışsal katmanı (betikler) korursunuz.
Henüz belirtimde olmayan uç noktaları nasıl ele alırım?
Belirtim odaklı bir iş akışında, belirtimde olmayan bir uç nokta test için hazır değildir. Bu katı gelebilir, ancak amaç budur: belirtim kapısı, yeni uç noktaların testler yazılmadan önce resmi olarak tanımlanmasını sağlar. Keşif geliştirme için yerel bir taklit (stub) üzerinde çalışabilir ve uç noktayı tanıtan PR'ın bir parçası olarak belirtim girdisini ekleyebilirsiniz. Belirtim odaklı düzenleme adımını hızlandıran araçlar için en iyi OpenAPI doğrulayıcı araçları kılavuzuna bakın.
Apidog Belirtim Odaklı Modu şu anda kullanılabilir mi?
Apidog Belirtim Odaklı Modu şu anda beta aşamasındadır. Apidog aracılığıyla erişebilir ve Git senkronizasyon iş akışının, dal desteğinin ve otomatik oluşturulmuş mock'ların ekibinizin gereksinimlerini karşılayıp karşılamadığını değerlendirebilirsiniz. Her beta özelliği gibi, üretim iş akışı olarak taahhüt etmeden önce kendi belirtim yapınıza karşı test etmeye değer.
Bununla belirtimi Postman'e aktarmak arasındaki fark nedir?
Postman bir OpenAPI belirtimini içe aktarabilir ve ondan bir koleksiyon oluşturabilir. Bu tek seferlik bir dönüştürmedir. Koleksiyon daha sonra belirtimden bağımsız olarak sürdürülür, bu nedenle sapma hemen yeniden başlar. Belirtim odaklı bir iş akışı, her CI çalıştırmasında (veya senkronizasyonda) koleksiyonu belirtimden yeniden oluşturur, böylece koleksiyon belirtimden en fazla bir derleme kadar geride kalır.
Sonuç
Ekibinizin yaşadığı sapma sorunu Postman'deki bir hata değildir. Bu, iki kısmen çakışan API açıklamasını, aralarında net bir bağımlılık olmadan sürdürmenin öngörülebilir sonucudur. Çözüm, Git'teki OpenAPI belirtimini yetkili kaynak olarak belirlemek ve Postman koleksiyonunu bu belirtimin aşağı akışında oluşturulmuş bir yapıt olarak ele almaktır.
Bu tersine çevirme, neyin ne zaman bozulduğunu değiştirir. Testleri bozan belirtim değişiklikleri, onları yapan PR'da yakalanır. Dokümantasyon, mock'lar ve test senaryoları aynı kaynaktan okudukları için hizalı kalır. İki sistemi senkronize tutmanın bakım yükü ortadan kalkar çünkü tek bir sistem vardır.
Apidog'u indirin ve mevcut OpenAPI belirtiminizle bir Belirtim Odaklı Mod çalışma alanı açın. Bir belirtimden ziyade bir koleksiyondan başlıyorsanız, koleksiyonu bir OpenAPI başlangıç noktası olarak içe aktarabilir ve oradan belirtim odaklı çalışmaya devam edebilirsiniz. Git senkronizasyon iş akışı, uydurulmuş bir örnek yerine kendi API'nize karşı çalışırken gördüğünüzde somutlaşır.