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

Swagger Postman kayması bir süreç hatası değildir. Aynı sözleşmeyi, onları senkronize tutacak hiçbir mekanizma olmadan iki yerde depoladığınızda ortaya çıkan şeydir. Bir OpenAPI spesifikasyonu yazarsınız, belgeler için Swagger UI'ı ona yönlendirirsiniz, sonra testler için bir Postman koleksiyonu dışa aktarırsınız. Bir hafta sonra, birisi YAML'ye dokunmadan koleksiyondaki bir uç noktayı değiştirir ve şimdi belgeleriniz ve testleriniz farklı API'leri açıklar. Bu makale, bu sonucun neden yapısal olarak garanti edildiğini ve tek bir gerçeklik kaynağı modelinin pratikte nasıl göründüğünü açıklar. Bir spesifikasyondan test oluşturma konusunda adım adım bilgi için, OpenAPI test üretimi hakkında mevcut nasıl yapılır kılavuzuna bakın.

button

İki dosya neden her zaman birbirinden uzaklaşır

Deponuzda bir openapi.yaml dosyası bulundurursunuz. Ayrıca bir Postman koleksiyonu da saklarsınız. Bu iki nesne aynı API sözleşmesini açıklar, ancak ayrı ayrı depolanır, farklı kişiler tarafından düzenlenir ve farklı programlarda güncellenir. Her iki araçta da bunlar arasında tutarlılığı zorlayan hiçbir şey yoktur.

Gerçekçi bir senaryoyu ele alalım. Arka uç ekibiniz, zorunlu bir reason alanı içeren yeni bir POST /payments/refund uç noktası yayınlar. Biri bunu Postman koleksiyonuna ekler, çünkü testlerini orada çalıştırırlar. openapi.yaml güncellemesi bir sprint birikim listesine gider. Üç gün sonra, bir ön uç geliştirici Swagger belgelerini okur, uç noktayı reason olmadan çağırır ve belgeden tek başına açıklayamadığı bir 400 hatası alır.

Temel sebep ihmal değildir. İki yapıt arasında herhangi bir bağlayıcılığın olmamasıdır. Her iki araç da diğerinin var olduğunu bilmez.

Yukarıdaki tablo sorunu açıkça göstermektedir. Üç satır, üç farklı güncelleme sahibi, sıfır çapraz doğrulama. YAML'nize Spectral gibi bir linter çalıştırsanız bile, şema hatalarını yakalar, ancak YAML ile tamamen başka bir araçta bulunan koleksiyon arasındaki boşlukları yakalamaz.

Üç kopya problemi

Stoplight gibi ayrı bir dokümantasyon platformu kullanan ekipler sorunu daha da karmaşık hale getirir. Artık sözleşmenin üç kopyasına sahipsiniz:

1. Git'e işlenmiş olan openapi.yaml.
2. Dışa aktarılan ve bir çalışma alanı olarak paylaşılan Postman koleksiyonu.
3. Stoplight'ta (veya Swagger UI'da veya bir wikide) oluşturulan dokümantasyon.

Her kopya bağımsız olarak kayabilir. OpenAPI Spesifikasyonu'nun kendisinin çalışma zamanı zorlama mekanizması yoktur. Bir açıklama formatıdır, senkronizasyon protokolü değildir. YAML'de istediğiniz herhangi bir API'yi açıklayabilirsiniz; Postman koleksiyonunuzun farklı bir şey yapmasını hiçbir şey engellemez.

Bu, Dünya Ekonomik Forumu'ndaki ekiplerin GitHub'da ayrı Postman koleksiyonları ve ayrı dokümantasyon siteleriyle OpenAPI spesifikasyonlarını sürdürürken karşılaştıkları baskıyla aynıdır. Aynı sözleşme için üç yer, üç hata noktası ve üç manuel senkronizasyon döngüsü anlamına gelir. Ekip büyüklüğü ve birden fazla hizmet eklendiğinde, bakım maliyeti doğrusal olmayan bir şekilde artar.

Kayma testleri nasıl sessizce bozar

Swagger Postman kaymasının sinsi kısmı, yanlış olsalar bile testlerin geçmeye devam etmesidir. Postman koleksiyonunuz hala eski istek gövdesi şemasını gönderiyorsa ve test arka ucunuz bir geçiş penceresi sırasında hem eski hem de yeni şemaları kabul ediyorsa, yeşil test çalışmanız mevcut spesifikasyonun kapsanıp kapsanmadığı hakkında hiçbir şey söylemez.

İşte güncel olmayan bir Postman koleksiyonunu atlatacak bir spesifikasyon değişikliğini gösteren somut bir YAML parçası:

# 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 YENİ 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

v1'de sabitlenmiş bir Postman koleksiyonu yalnızca transaction_id gönderir. Arka uç ekibi dağıtım sırasında reason için hoşgörülü bir varsayılan eklerse, eski Postman testi geçer. Spesifikasyon reason'ın zorunlu olduğunu söyler; test asla göndermez. Bir ön uç entegrasyonu staging ortamında kırılana kadar kimse fark etmez.

YAML'nize uygun bir OpenAPI doğrulayıcı çalıştırmak, spesifikasyon içindeki şema tutarsızlıklarını yakalar. Ancak spesifikasyon ile Postman koleksiyonunuzun gerçekte gönderdiği arasındaki boşluğu yakalamaz.

OpenAPI odaklı testin gerçekte ne anlama geldiği

OpenAPI odaklı test, spesifikasyonun yetkili kaynak olduğu anlamına gelir. Testler ondan türetilir, onunla paralel olarak yazılmaz. Spesifikasyon değiştiğinde, testler bu değişikliği otomatik olarak yansıtır çünkü aynı kaynağı paylaşırlar.

Bu, "Swagger'ı Postman'a aktarmak"tan farklıdır. Aktarım, tek seferlik bir kopyalama işlemidir. Aktara basarsınız, bir koleksiyon alırsınız ve iki nesne hemen tekrar bağımsız hale gelir. Bir sonraki spesifikasyon değişikliği, başka bir manuel aktarım veya başka bir manuel koleksiyon düzenlemesi gerektirir. Kaymayı çözmediniz; sıfırladınız.

Gerçek spesifikasyon-önce yaklaşımı şöyle görünür:

1. OpenAPI dosyası, ana sözleşme olarak Git'te yaşar.
2. Bir araç bu dosyayı okur ve ondan sahte sunucular, belgeler ve test senaryoları türetir.
3. Dosya değiştiğinde (PR incelemesi yoluyla), sahte sunucular ve test senaryoları güncellenir.
4. Senkronize tutulacak ayrı bir koleksiyon yoktur.

Spesifikasyon-önce API geliştirme modeli, daha geniş iş akışı felsefesini açıklar. Bu makale, belgeler ve testler arasındaki kayma sorununa odaklanmaktadır.

Tek bir spesifikasyon üzerinde yürütme katmanı olarak Apidog

Apidog'un modeli, Git'i gerçeklik kaynağı, Apidog'u ise bunun üzerindeki yürütme katmanı olarak ele alır. openapi.yaml dosyanızı commit edersiniz. Apidog onu okur ve bu tek dosyadan üç çıktı üretir: etkileşimli dokümantasyon, bir mock sunucu ve bir test paketi.

Apidog'un Spesifikasyon-Önce Modu (şu anda beta sürümünde) tam olarak bu iş akışı için tasarlanmıştır. Bunu OpenAPI dosyanıza işaret edersiniz ve platform, ayrı bir koleksiyon tutmanıza gerek kalmadan üç çıktıyı da türetir. YAML'yi güncelleyip push ettiğinizde, alt akış çıktıları güncellenir.

Pratikteki sonuç, kayma yapacak bir Postman koleksiyonunun olmamasıdır. Tek bir dosya vardır. OpenAPI spesifikasyonunu GitHub ile senkronize etme iş akışı, ekiplerin spesifikasyonları GitHub'a nasıl işleyeceğini ve Apidog'u nasıl uyumlu tutacağını kapsar.

Postman merkezli bir iş akışından gelen ekipler için, deneme sürümünde doğrulanması gereken konular: Apidog'un belirli şema karmaşıklığınızla veri odaklı test senaryolarını nasıl ele aldığı ve rapor görünürlüğü izinlerinin kuruluşunuzun erişim modeliyle eşleşip eşleşmediği. Bunlar, bir üretim paketini geçirmeden önce iyi POC sorularıdır.

API mocking de resmin önemli bir parçasıdır. Bir mock, testlerle aynı spesifikasyondan türetildiğinde, mock'u çağıran bir ön uç geliştiricisi, testlerin doğruladığıyla tutarlı bir yanıt alır. Mocking'in nereye uyduğu hakkında daha fazla bilgi için API mocking kullanım durumları bölümüne bakın.

Geçiş yolu nasıl görünüyor

Bir Swagger + Postman kurulumundan geliyorsanız, geçiş büyük bir "big-bang" değişimi değildir. Makul bir sıra:

1. Mevcut openapi.yaml dosyanızı Postman koleksiyonunuza karşı denetleyin. Koleksiyonda spesifikasyonda olmayan her uç noktayı ve koleksiyonun kapsamadığı her spesifikasyon uç noktasını bulun.
2. Spesifikasyonu uzlaştırın. İlk YAML'yi yazdığınız zamanki API'yi değil, gerçek mevcut API'yi tanımlamalıdır.
3. Spesifikasyonu Apidog'a aktarın. Apidog'un spesifikasyon yapısından başlangıç test paketini oluşturmasına izin verin.
4. Postman koleksiyonunu kademeli olarak kullanımdan kaldırın. Sonuçları karşılaştırmak için bir sprint boyunca ikisini paralel olarak çalıştırın.
5. Koleksiyonu arşivleyin. Git, gerçeklik kaynağı olmaya devam etsin. Apidog yürütmeyi üstlensin.

Adım 1 genellikle en rahatsız edicidir, çünkü iki yapıtın ne kadar uzaklaştığını ortaya çıkarır. Altı ay boyunca kaymanın birikmesine izin veren ekipler, genellikle %20 ila %40 oranında uç nokta kapsama boşlukları bulurlar.

Spesifikasyonunuzdan ilk test koleksiyonunu oluşturmak için, OpenAPI spesifikasyonlarından test koleksiyonları oluşturma konusundaki özel nasıl yapılır kılavuzu mekaniği ayrıntılı olarak kapsar. Bu makale bu adımdan önce bilinçli olarak durmaktadır; temiz bir spesifikasyona sahip olduğunuzda oluşturma eğitimi daha iyi bir referanstır.

Karşılaştırma: Çift Bakım vs. Kaynak Olarak Spesifikasyon

Çift bakım sütunu, Postman'ın bir araç olarak başarısızlığı değildir. Postman, koleksiyon tabanlı testlerde güçlüdür ve geniş bir ekosisteme sahiptir. Sorun, bir koleksiyonu türetilmiş bir yapıt yerine paralel bir sözleşme olarak ele alma iş akışı modelidir.

Sıkça Sorulan Sorular

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

Aktarım, anlık bir kopya oluşturur. Aktarımdan sonra, iki nesne bağımsız hale gelir. openapi.yaml dosyanızdaki bir sonraki değişiklik, koleksiyona otomatik olarak yayılmaz. Her spesifikasyon değişikliğinde yeniden aktarmanız veya koleksiyonu manuel olarak düzenlemeniz gerekir, bu da sizi çift bakım sorununa geri döndürür.

Spesifikasyon-önce modelini benimserken Postman'ı keşif testleri için kullanmaya devam edebilir miyim?

Evet. Spesifikasyon-önce yaklaşımı, özel testleri yasaklamaz. Otomatikleştirilmiş regresyon paketinizi spesifikasyon odaklı bir çalıştırıcıya taşırken, tek seferlik keşif çağrıları için Postman'ı kullanmaya devam edebilirsiniz. Önemli olan, keşif amaçlı koleksiyonu sözleşme doğrulaması için bir gerçeklik kaynağı olarak taahhüt etmemektir.

Spesifikasyonumun gerçek API uygulamasından ne zaman saptığını nasıl anlarım?

En güvenilir kontrol, bir sözleşme test katmanıdır. API sunucunuz, test zamanında gelen istekleri ve giden yanıtları OpenAPI spesifikasyonuna göre doğrulayabilir. Spectral gibi araçlar, spesifikasyonu dahili tutarlılık açısından kontrol eder, ancak uygulama kaymasını yakalamak için çalışma zamanı doğrulamasına ihtiyacınız vardır. Bu, Swagger-Postman kaymasından ayrı bir konudur, ancak her ikisi de mevcut olduğunda sorunu karmaşıklaştırır.

Apidog Postman'ı tamamen değiştiriyor mu?

Bu, ekibinizin iş akışına bağlıdır. Apidog, tek bir çalışma alanından tasarım, mocking, test ve belgeleri yönetir. Postman'ı öncelikle sözleşme testleri ve regresyon paketleri için kullanan ekipler için Apidog bu alanı kapsar. Ekibiniz CI'da Postman'ın koleksiyon çalıştırıcısını kullanıyorsa veya kapsamlı koleksiyon betiklerine sahipse, Postman ile test etme, spesifikasyon-önce tasarım iş akışının yanı sıra bir seçenek olmaya devam eder. Her ikisini de bir deneme sprintinde değerlendirmeye değer.

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

Spesifikasyonu uzlaştırmak bir ön koşuldur. Kestirme yol yoktur. Spesifikasyonu gerçek API davranışı ile karşılaştırırsınız, YAML'yi gerçeği yansıtacak şekilde güncellersiniz ve ardından onu gelecekteki ana kaynak olarak ele alırsınız. Yukarıdaki geçiş yolundaki denetim adımı, bu çalışmanın yapıldığı yerdir.

Sonuç

Swagger belgeleri ve Postman koleksiyonları, aralarında hiçbir bağlayıcılık olmayan iki ayrı yapıt oldukları için kayma yaşarlar. Bu, çift bakım iş akışının yapısal bir özelliğidir, bir ekip disiplini sorunu değildir. Çözüm, ikinci yapıtı ortadan kaldırmaktır: Git'te tek bir OpenAPI dosyası, her birinin bağımsız yaşamasından ziyade mock'ları, testleri ve belgeleri ondan türeten bir araçla.

Apidog'u indirin ve mevcut OpenAPI spesifikasyonunuzu içe aktarın. Tek bir oturumda, tek bir dosyanın hem Swagger belgenizi hem de Postman koleksiyonunuzu nasıl değiştirdiğini, mock'lar, testler ve belgelerin hepsinin aynı kaynaktan okuduğunu görebilirsiniz. Spesifikasyon-Önce Modu'nu (şu anda beta sürümünde) değerlendiriyorsanız, güncel özellik kapsamı ve erişim ayrıntıları için Apidog Spesifikasyon-Önce Modu sayfasına bakın.