TL;DR
SwaggerHub senkronizasyon çakışmaları, eşzamanlı düzenlemeler veya Git entegrasyonu çakışan spesifikasyon versiyonları oluşturduğunda meydana gelir. Çözüm, çakışan versiyonları belirlemeyi, değişiklikleri manuel olarak birleştirmeyi ve yeniden commit etmeyi içerir. Çözmekten daha iyisi önlemektir – net sahiplik, dal disiplini ve kilitleme kuralları çoğu çakışmayı oluşmadan önce azaltır. Apidog'un dallanma modeli, eşzamanlı düzenleme çakışmalarını tasarım gereği azaltır.
Giriş
SwaggerHub'ın işbirlikçi düzenleme özellikleri gerçekten kullanışlıdır. Birden fazla ekip üyesi aynı API tanımı üzerinde çalışabilir, değişiklikler neredeyse gerçek zamanlı olarak görülebilir ve Git entegrasyonu, ekiplerin spesifikasyonları kaynak depolarıyla senkronize etmelerini sağlar.
Ancak işbirliği çakışmalara yol açar. İki mühendis aynı uç noktayı aynı anda düzenler. Bir spesifikasyon SwaggerHub'da ve ayrı olarak GitHub'da güncellenir ve senkronizasyon süreci farklı versiyonlarla karşılaşır. Bir Alan (Domain) güncellenirken bir API inceleme ortasındadır. Bu çakışmalar yönetilebilir, ancak beklenmedik bir şekilde ortaya çıktıklarında ve ekiplerin net bir çözüm süreci olmadığında aksaklıklara neden olurlar.
Bu kılavuz, SwaggerHub'da ortaya çıkan çakışma türlerini, her türün nasıl çözüleceğini ve daha iyi iş akışı disipliniyle nasıl önleneceğini açıklamaktadır. Son bölüm, Apidog'un aynı sorun sınıfını nasıl ele aldığını anlatmaktadır.
SwaggerHub'da senkronizasyon çakışması türleri
1. Eşzamanlı düzenleme çakışmaları. SwaggerHub, birden fazla kullanıcının aynı anda bir API tanımını düzenlemesine izin verir. İki kullanıcı spesifikasyonun aynı bölümünü eşzamanlı olarak düzenlediğinde, son kaydeden kazanır. Birleştirme olmaz – ikinci kaydetme, ilk kullanıcının değişikliklerinin üzerine yazar. Bu teknik olarak Git anlamında bir "çakışma" değildir (bir hata durumu yoktur), ancak ekipler dikkatli olmazsa veri kaybına neden olur.
2. SwaggerHub'dan Git'e senkronizasyon çakışmaları. SwaggerHub, GitHub, GitLab ve Bitbucket ile entegre olur. Bir spesifikasyon SwaggerHub'da kaydedildiğinde, yapılandırılmış bir depoya otomatik olarak gönderilebilir. Bir spesifikasyon dosyası doğrudan depoya commit edildiğinde, SwaggerHub'a geri senkronize edilebilir. Her ikisi de bağımsız olarak gerçekleşirse, SwaggerHub'ın senkronizasyon sürecinin otomatik olarak uzlaştıramayacağı çakışan versiyonlar elde edersiniz.
3. API versiyonu çatallanma (fork) çakışmaları. SwaggerHub'da yeni bir çalışma dalı oluşturmak için bir API versiyonunu çatalladığınızda ve ardından değişiklikleri geri birleştirmeye çalıştığınızda, çatallanma ile orijinal arasındaki farklılıklar manuel çözüm gerektiren çakışmalar oluşturabilir.
4. Alan (Domain) versiyon uyumsuzluk çakışmaları. Bir API, belirli bir versiyonda bir SwaggerHub Alanına başvuruyorsa ve o Alan versiyonu kullanımdan kaldırılmış veya uyumsuz bir şekilde değiştirilmişse, başvuran API çözüm hatalarıyla karşılaşabilir. Bu başlı başına bir senkronizasyon çakışması değildir, ancak benzer aksaklıklara neden olur ve benzer çözüm adımları gerektirir.
5. Bağlı depolarda Git çekme (pull) çakışmaları. SwaggerHub'a bağlı Git deposunun, spesifikasyon dosyasında çakışmalara neden olan dalları veya birleştirmeleri olduğunda, SwaggerHub senkronizasyon süreci bir sonraki senkronizasyonda bu çakışmaları yüzeye çıkaracaktır.
Eşzamanlı düzenleme çakışmalarını çözme
Bu tür "çakışma" en yaygın ve en görünmez olanıdır. Bir hata mesajı yoktur – bir kullanıcının değişiklikleri basitçe kaybolur.
Çözüm:
- Başka bir ekip üyesi kaydettikten sonra değişikliklerin eksik olduğunu fark ederseniz, neyin üzerine yazıldığını görmek için SwaggerHub'ın değişiklik geçmişini (planınızda mevcutsa) kontrol edin.
- Son kaydeden ekip üyesinden mevcut spesifikasyon durumunu kendi yerel kopyasıyla karşılaştırmasını isteyin.
- Eksik değişiklikleri manuel olarak yeniden girin.
Önleme tek gerçek çözümdür. Aşağıdaki önleme bölümüne bakın.
SwaggerHub'dan Git'e senkronizasyon çakışmalarını çözme
SwaggerHub ve Git deponuz ayrıştığında, tipik olarak SwaggerHub'ın Git entegrasyon panelinde, uzak depoda SwaggerHub'ın versiyonunda olmayan değişiklikler olduğu için otomatik gönderim yapamayacağını belirten bir senkronizasyon hatası görürsünüz.
Çözüm adımları:
Adım 1: Git deponuzdan mevcut spesifikasyonu çekin. Çakışmaya neden olan daldan YAML veya JSON dosyasını indirin.
Adım 2: SwaggerHub'dan mevcut spesifikasyonu çekin. API'yi SwaggerHub'dan YAML olarak dışa aktarın.
Adım 3: İki dosyayı karşılaştırın (diff). Herhangi bir diff aracını (diff, VS Code'un diff görünümü veya OpenAPI uyumlu bir diff aracı) kullanın. Git'te olup SwaggerHub'da olmayan değişiklikleri ve tersini belirleyin.
Adım 4: Manuel olarak birleştirin. Her iki değişiklik kümesini de içeren uzlaştırılmış bir spesifikasyon versiyonu oluşturun. Bu insan yargısı gerektirir – otomatik bir birleştirme aracı sözdizimsel olarak geçerli ancak anlamsal olarak yanlış YAML üretebilir.
Adım 5: Tek bir gerçeklik kaynağı seçin. SwaggerHub'ın mı yoksa Git'in mi yetkili kaynak olduğuna karar verin, ardından diğerini güncelleyin. Git yetkiliyse, birleştirilmiş spesifikasyonu depoya commit edin ve senkronizasyonun onu SwaggerHub'a çekmesini sağlayın. SwaggerHub yetkiliyse, birleştirilmiş spesifikasyonu SwaggerHub'dan Git'e gönderin.
Adım 6: Senkronizasyonu doğrulayın. Güncelledikten sonra, SwaggerHub'ın Git entegrasyon panelinin çakışma olmadan temiz bir senkronizasyon durumu gösterdiğini onaylayın.
Kullanışlı bir araç: openapi-diff. Birkaç OpenAPI diff aracı, spesifikasyon versiyonlarını satır satır değil, anlamsal düzeyde (uç nokta eklemeleri, alan değişiklikleri, bozucu veya bozucu olmayan değişiklikler) karşılaştırır. oasdiff veya openapi-diff gibi araçlar, ham YAML diff'e göre daha net çıktı verir.
Alan (Domain) versiyon uyumsuzluk çakışmalarını çözme
API'niz değişmiş veya kullanımdan kaldırılmış bir Alan versiyonuna başvuruyorsa:
Adım 1: API'nizin hangi Alan versiyonuna başvurduğunu belirleyin. Spesifikasyonunuzdaki $ref URL'lerine bakın – sürüm numarasını içerirler.
Adım 2: Alan versiyonunun değişiklik günlüğünü inceleyin. Mevcut sabitlenmiş versiyonunuz ile en son versiyon arasında neyin değiştiğini kontrol edin.
Adım 3: Değişikliklerin bozucu olup olmadığını değerlendirin. Yeni isteğe bağlı alanlar eklemek bozucu değildir. Alanları kaldırmak, türleri değiştirmek veya özellikleri yeniden adlandırmak bozucu değişikliklerdir.
Adım 4: Geçiş yapmaya karar verirseniz, API'nizin $ref yollarını yeni Alan versiyonuna başvuracak şekilde güncelleyin. Güncellemeden sonra spesifikasyonun hala doğru şekilde doğrulandığını test edin.
Adım 5: Ekibi güncelleyin. Alan değişikliği birden fazla API'yi etkiliyorsa, tüm ekiplerin aynı zaman çizelgesinde güncelleme yapması için geçişi koordine edin.
API versiyonu çatallanma (fork) çakışmalarını çözme
Çatallanmış bir API versiyonunu ana versiyona geri birleştirirken:
Adım 1: Hem çatallanmış hem de ana versiyonu YAML dosyaları olarak dışa aktarın.
Adım 2: İki spesifikasyonu bir OpenAPI diff aracı kullanarak karşılaştırın.
Adım 3: SwaggerHub düzenleyicisinde, çatallanmış versiyondan gelen değişiklikleri ana versiyona manuel olarak uygulayın (veya tersi, amaçlanan son duruma bağlı olarak).
Adım 4: Birleştirilmiş spesifikasyonu SwaggerHub'ın düzenleyicisinde doğrulayarak doğrulama hataları olmadığını onaylayın.
Adım 5: Artık gerekmiyorsa çatallanmayı silin veya arşivleyin.
Önleme: çakışmaları oluşmadan önce azaltma
Net sahiplik bölgeleri oluşturun. Büyük bir API spesifikasyonunun farklı bölümlerini farklı ekip üyelerine atayın. Bir kişi kimlik doğrulama uç noktalarına, diğeri kaynak uç noktalarına sahiptir. Çakışan düzenleme bölgeleri, eşzamanlı çakışmaların meydana geldiği yerlerdir.
Önemsiz olmayan değişiklikler için çatallanma kullanın. Bir saatten fazla sürecek veya inceleme gerektiren herhangi bir değişiklik için, düzenlemeden önce API versiyonunu çatallayın. Bu, çalışmanızı birleştirmeye hazır olana kadar ana versiyondan ayırır.
Bir Git-senkronizasyon protokolü oluşturun. Git entegrasyonu kullanıyorsanız, hangi yönün yetkili olduğuna karar verin ve belgeleyin. "SwaggerHub düzenleyicidir; Git kayıttır" veya "Git doğruluk kaynağıdır; SwaggerHub ondan senkronize olur" – her iki tarafta da bağımsız düzenlemelerle aynı anda ikisi birden olmasın.
Paylaşılan alanları düzenlemeden önce iletişim kurun. Başkalarının da dokunması gerekebilecek bir bölümü düzenlemek üzere olduğunuzu bildirmek için Slack, bir bilet sistemi veya SwaggerHub'ın kendi yorum özelliğini kullanın. Asenkron iletişim, çoğu eşzamanlı düzenleme üzerine yazmayı önler.
Alan (Domain) referanslarını açıkça sabitleyin. $ref yollarınızda her zaman belirli bir Alan versiyonuna başvurun, kayan bir "en son" referansa değil. Bu, kasıtlı bir işlem olmadan otomatik bozucu değişikliklerin API'nize akmasını engeller.
Otomatik gönderme (auto-push) ayarlarını dikkatlice yapın. SwaggerHub'ın kaydetme üzerine otomatik gönderme özelliği kullanışlı olabilir ancak ekip üyeleri Git deposunda da doğrudan spesifikasyon değişiklikleri commit ediyorsa çakışma riski oluşturur. Geliştiriciler her iki yerde de spesifikasyon değişiklikleri yapıyorsa otomatik göndermeyi devre dışı bırakın.
Apidog aynı sorunları nasıl ele alıyor?
Apidog'un işbirliği modeli, bu çakışma modellerinin çoğunu tasarım gereği önleyen Git tarzı dallanma üzerine kurulmuştur.
Eşzamanlı üzerine yazma yok. Apidog'da ekip üyeleri ayrı dallar üzerinde çalışır. Yeni bir uç nokta oluşturan bir mühendis bir dal oluşturur, işi yapar ve bittiğinde bir inceleme isteği açar. Farklı bir değişiklik yapan başka bir mühendis de aynı şeyi ayrı bir dalda yapar. Değişiklikler incelenip onaylanana kadar ana dala birleştirilmez. Bu, "son kaydeden kazanır" üzerine yazma sorununu tamamen ortadan kaldırır.
Dahili inceleme kapısı. İnceleme ve onay iş akışı, spesifikasyon değişikliklerinin ana dalı veya alt akım ekiplerinin kullandığı dokümantasyonu etkilemeden önce açık bir doğrulama adımından geçtiği anlamına gelir.
Birleştirmede çakışma tespiti. İki dal aynı uç noktayı veya şemayı değiştirdiğinde, Apidog'un birleştirme süreci çakışmayı açıkça yüzeye çıkarır. Ekip, her iki değişiklik kümesine de net bir bakış açısıyla çözer.
Yerel öncelikli iş akışı. Harici Git depolarıyla senkronizasyon çakışmaları konusunda endişe duyan ekipler için Apidog'un yerel iş akışı, etki alanını azaltır – değişiklikler Git'e commit edilmeden önce platformda doğrulanır.
Sıkça Sorulan Sorular
SwaggerHub'da yerleşik bir çakışma çözme kullanıcı arayüzü var mı? SwaggerHub'ın bazı Git GUI araçları gibi grafiksel bir birleştirme çakışması çözme arayüzü yoktur. Çakışma çözümü manueldir – her iki versiyonu indirin, SwaggerHub dışında karşılaştırın ve çözümlenmiş versiyonu yükleyin.
Çakışma çözümü sırasında kullanılacak en iyi OpenAPI diff aracı nedir? oasdiff, OpenAPI spesifikasyonlarının yapılandırılmış farklılıklarını üreten, bozucu değişiklikleri bozucu olmayan eklemelerden ayrı olarak işaretleyen iyi bakımlı bir komut satırı aracıdır. API spesifikasyon çalışmaları için ham YAML diff'ten daha kullanışlı bir çıktıdır.
SwaggerHub'da başkalarının düzenlemesini engellemek için bir API'yi kilitleyebilir miyim? SwaggerHub'ın yerleşik bir dosya kilitleme mekanizması yoktur. En yakın geçici çözüm, siz değişiklik yaparken düzenleme izinlerini geçici olarak kısıtlamak, ardından geri yüklemek için SwaggerHub'ın rol sistemini kullanmaktır.
Çakışan bir API'nin hangi versiyonunun doğru olduğunu nasıl anlarım? Kimin ne zaman hangi değişiklikleri yaptığını görmek için SwaggerHub'ın etkinlik günlüğünü (planınız içeriyorsa) kontrol edin. Git kullanıyorsanız, commit geçmişi güvenilir bir kayıttır. Hiçbiri kesin değilse, niyeti yeniden oluşturmak için ilgili ekip üyelerine danışın.
SwaggerHub, bağımlı olduğum bir Alanın güncellendiğinde beni bilgilendiriyor mu? SwaggerHub, bildirim sistemi aracılığıyla Alan güncellemeleri hakkında sizi bilgilendirebilir. Bunu yapılandırıp yapılandırmadığınız, bildirim ayarlarınıza bağlıdır. Alan değişiklikleri için uyarıları yapılandırmak için Kuruluş Ayarları > Bildirimler bölümünü kontrol edin.
Apidog'a geçiş tüm senkronizasyon çakışmalarını önler mi? Dallanma, çakışmaların sıklığını önemli ölçüde azaltır, ancak onları tamamen ortadan kaldırmaz. Aynı uç noktayı değiştiren iki dalın birleştiğinde yine de uzlaştırılması gerekir. Dallanmanın yaptığı, bu çakışmaları sessiz üzerine yazmalar yerine görünür ve açık hale getirmektir.
SwaggerHub'daki senkronizasyon çakışmaları çoğunlukla bir ürün sorunundan ziyade bir iş akışı sorunudur. Net sahiplik, dal disiplini ve tanımlanmış bir Git-senkronizasyon protokolü, çoğu sorunu ortaya çıkmadan önce önler. Çakışmalar meydana geldiğinde, metodik bir süreç – her iki versiyonu dışa aktarma, uygun bir araçla karşılaştırma, manuel olarak birleştirme, doğrulama ve senkronizasyonu doğrulama – onları güvenilir bir şekilde çözer. Apidog'un dallanma modeli, paralel çalışmayı açık hale getirerek çakışmaların sıklığını azaltır, ancak herhangi bir işbirlikçi düzenleme aracı aynı temel disiplinden faydalanır.