Apidog GitHub ve GitLab'e Nasıl Bağlanır

API belirtimleriniz Apidog'da bulunsa da doğruluk kaynağınız Git'te yaşıyorsa, ikisinin uyumlu olmasını istersiniz. Apidog Git entegrasyonu bu boşluğu kapatır. Bir GitHub, GitLab veya Azure DevOps deposunu projenize bağlamanıza, OpenAPI belirtimlerinizi sürüm kontrolüne aktarmanıza ve depo değişikliklerini Apidog'a geri çekmenize olanak tanır. Temiz bir denetim izi, belirtim değişiklikleri üzerinde kod incelemesi ve uygulamanın içinde olabilecek her şeye dayanabilen bir yedekleme elde edersiniz.

Bu, geniş bir referanstır. Apidog'un desteklediği her sağlayıcıyı, ürünün Git ile iletişim kurduğu her iki yolu ve karşılaşacağınız pratik kararları kapsar: hangi depo, hangi dal, kimler push yapabilir ve bir şeyler bozulduğunda ne yapılmalı. Yalnızca odaklanmış GitHub rehberine ihtiyacınız varsa, OpenAPI belirtiminizi GitHub ile nasıl senkronize edeceğinize dair özel rehberi okuyun. Burada, daha geniş bir bakış açısı sunuyoruz.

Apidog Git entegrasyonu ne işe yarar?

Apidog, Git ile iki farklı şekilde iletişim kurar. Farklı sorunları çözerler ve birini, diğerini veya her ikisini kullanabilirsiniz. Bunları karıştırmak en yaygın kafa karışıklığı kaynağıdır, bu yüzden önce onları ayıralım.

İlk yetenek, Belirtim-Önce Modu (Spec-First Mode) aracılığıyla iki yönlü senkronizasyondur. OpenAPI belgenizi Apidog'un IDE tarzı düzenleyicisinde YAML veya JSON olarak düzenler, değişikliklerinizi commit eder ve bağlı dala push yaparsınız. Başka biri depodaki belirtimi güncellediğinde, bu değişiklikleri Apidog'a geri çekersiniz. Bu gerçek bir gidiş-dönüş sürecidir: düzenlemeler Git'e akar ve depo değişiklikleri geri gelir.

İkinci yetenek ise API belirtimlerinin otomatik Git yedeklemesidir. Burada Apidog, her modülün OpenAPI/Swagger dosyasını dışa aktarır ve belirlenmiş bir zaman çizelgesine göre bir depoya push yapar. Bu tek yönlü ve müdahalesizdir. Bir kez yapılandırırsınız ve sistem, sizin parmağınızı bile oynatmadan belirtimlerinizin sürümlü bir kopyasını Git'te tutar. Bu bir güvenlik ağıdır, bir düzenleme iş akışı değildir.

Bu ayrımı makalenin geri kalanında aklınızda bulundurun. "Senkronizasyon" dediğimizde, iki yönlü Belirtim-Önce Modu akışını kastediyoruz. "Yedekleme" dediğimizde ise, zamanlanmış, tek yönlü dışa aktarımı kastediyoruz.

Desteklenen Git sağlayıcıları

Apidog, çoğu ekibin zaten kullandığı üç sağlayıcıyı destekler. GitHub ve GitLab, kendi yerel yetkilendirme akışları aracılığıyla doğrudan bağlanır. Azure DevOps, standart HTTPS kimlik doğrulaması kullanan herhangi bir Git ana bilgisayarıyla çalışan genel bir Git Bağlantısı aracılığıyla bağlanır.

Genel Git Bağlantısı bir kaçış noktasıdır. Ana bilgisayarınız adı GitHub veya GitLab olmasa bile, standart Git'i HTTPS üzerinden token kimlik doğrulaması ile konuşuyorsa, genel bağlantı genellikle bunu halleder. Azure DevOps başlık vakasıdır, ancak aynı yol, bir HTTPS klonlama URL'si sunan kendi kendine barındırılan kurulumları da kapsar.

Git sağlayıcınızı bağlama

Bağlantı adımı, Apidog'a deponuzu okuma ve yazma erişimi verdiğiniz yerdir. Mekanizmalar sağlayıcıya göre biraz farklılık gösterse de, genel şekil aynıdır: yetkilendirme, depo seçimi, dal seçimi.

GitHub için, GitHub'ın OAuth ekranı aracılığıyla yetkilendirme yaparsınız. Apidog, belirtimi okuyabilmek ve commit'leri push edebilmek için depo erişimi ister. Depo bir organizasyona aitse, GitHub isteği üçüncü taraf erişimini onaylayan bir organizasyon yöneticisi aracılığıyla yönlendirebilir. Kişisel depolar, kendi hesabınız altında hemen yetkilendirilir.

GitLab için akış GitHub'ı yansıtır. GitLab'ın OAuth ekranı aracılığıyla giriş yapar ve depo erişimi verirsiniz. Kendi kendine yönetilen GitLab, Apidog'un ağ üzerinden örneğe ulaşabildiği sürece çalışır.

Azure DevOps için genel Git Bağlantısını kullanırsınız. OAuth el sıkışması yerine, deponun HTTPS klonlama URL'sini ve kişisel erişim belirtecini (PAT) sağlarsınız. PAT'yi Azure DevOps'ta kod okuma ve yazma izniyle oluşturun, ardından Apidog'a yapıştırın. Belirteç, Apidog'un commit'leri push etmesini sağlayan kimlik bilgisidir, bu nedenle onu tam olarak ihtiyaç duyduğu depolara göre ayarlayın.

Zaman kazandıran birkaç izin notu:

• Organizasyon vs kişisel depolar. Organizasyon depoları genellikle bir yöneticinin entegrasyonu bir kez onaylamasını gerektirir. Yetkilendirmeniz başarılı gibi görünse de Apidog depoyu göremiyorsa, genellikle bir yönetici onayı eksiktir.
• Belirteci sıkıca sınırlayın. Azure DevOps ve herhangi bir genel bağlantı için, PAT'ye yalnızca hedef proje için kod okuma/yazma izni verin. Tam hesap belirteçlerinden kaçının.
• Özel depolar sorun değil. Apidog özel depolarla çalışır. Erişim, sağladığınız yetkilendirme veya belirteçten gelir, genel görünürlükten değil.

Sağlayıcı bağlandıktan sonra, genellikle main olan bir depo ve bir daldan Apidog projesini oluşturursunuz. Bu eşleştirme, belirtimlerinizi sürüm kontrolünde belirli bir yere bağlar. Daha geniş pratiğe yeniyseniz, her şeyi bağlamadan önce benimsemeye değer kuralları Git ile OpenAPI sürüm kontrolü rehberimiz kapsar.

Belirtim-Önce Modu ile iki yönlü senkronizasyon

İki yönlü senkronizasyon Belirtim-Önce Modu'nda yer alır. Bu mod, Apidog'u diğer tüm kodlar gibi Git'e commit yapan bir belirtim düzenleyicisine dönüştürür. Tam referansı resmi Apidog dokümantasyonunda okuyabilirsiniz; işte gidiş-dönüş sürecinin pratikte nasıl çalıştığı.

OpenAPI belgesini doğrudan YAML veya JSON olarak düzenlersiniz. Düzenleyici IDE tarzındadır: sözdizimi vurgulama, canlı doğrulama ve otomatik tamamlama sunar, böylece hatalı bir $ref veya eksik bir gerekli alan, push yaptıktan sonra değil, yazarken ortaya çıkar. Siz düzenlerken, sol kenar çubuğu belgeyi otomatik olarak bir taslağa, yollara, işlemlere ve şemalara ayrıştırır, böylece büyük bir belirtimde ham metin üzerinde gezinmeden dolaşabilirsiniz.

Tipik bir düzenleme şöyle görünür. Diyelim ki bir uç nokta eklediniz:

paths:
 /v1/orders/{orderId}:
 get:
 operationId: getOrder
 summary: Retrieve a single order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: The requested order
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Order'

Bu değişikliği kaydettiğinizde, Apidog bunu yerel bir düzenleme olarak hazırlar. Ardından bir mesajla commit yapar ve bağlı dala push edersiniz, tıpkı herhangi bir Git iş akışında yapacağınız gibi. Push işlemi tamamlandığında, bir senkronizasyon göstergesi "Şimdi senkronize edildi" şeklinde okunur, bu da Apidog'un ve dalın aynı içeriği barındırdığına dair onayınızdır.

Çekme (pull) yönü de aynı derecede önemlidir. Bir ekip arkadaşı depodaki belirtimi düzenleyip push yaptığında, yerel kopyanızı güncel hale getirmek için bu değişiklikleri Apidog'a çekersiniz. Entegrasyonu gerçekten iki yönlü yapan budur: depo sadece bir yedekleme hedefi değil, bir eşittir.

Saklamak istemediğiniz düzenlemeler yaparsanız, commit etmeden önce push edilmemiş düzenlemeleri atabilirsiniz. Bu, çalışma kopyanızı en son senkronize edilmiş duruma geri döndürür, bu da deney yaparken ve değişikliği saklamaya değmeyeceğine karar verdiğinizde kullanışlıdır.

Bu commit-ve-push ritmi, Git-yerel API iş akışının kalbidir; belirtim değişiklikleri, kod tabanınızın geri kalanıyla aynı inceleme, geçmiş ve geri alma mekanizmalarından geçer. İncelemeciler bir çekme isteğindeki YAML farkı üzerine yorum yapar, onaylar birleştirmeyi kilitler ve API tasarım geçmişiniz, kod geçmişi gibi okunur.

API belirtimlerinin otomatik Git yedeklemesi

Yedekleme yeteneği, Apidog Git entegrasyonunun daha sessiz yarısıdır ve kurulumdan sonra sizden neredeyse hiçbir şey istemez. Bir modülü bir depoya işaret edersiniz ve gerisini Apidog halleder.

İşte mekanizma. Apidog, her modülün OpenAPI/Swagger dosyasını bir Git deposuna yedekleyebilir; GitHub, GitLab ve Azure DevOps hepsi desteklenir. Yedekleme yapılandırmasını kaydettiğinizde, sistem modülün OpenAPI Belirtim dosyasını belirtilen depoya otomatik olarak push eder. Push işlemi, gece rastgele belirlenen yoğun olmayan bir zaman diliminde gerçekleşir, bu da çalışma saatlerinizin dışında kalır ve yükü yayar.

Depolanan şey, o modülün dışa aktarılmış OpenAPI/Swagger belgesidir, API sözleşmesinin mevcut halinin bir anlık görüntüsüdür. Her push bir commit olduğu için, Git'te bir sürüm geçmişi biriktirirsiniz. Geçen haftanın sözleşmesini bugünküyle karşılaştırabilir, bir alanın ne zaman değiştiğini tam olarak görebilir ve ihtiyaç duyduğunuzda doğrudan depodan önceki bir sürümü geri yükleyebilirsiniz.

Yedekleme akışı tasarım gereği tek yönlüdür. Apidog depoya yazar; ondan değişiklikleri geri okumaz. Depo düzenlemelerinin Apidog'a akmasını istiyorsanız, bu yedeklemenin değil, Belirtim-Önce Modu'nun işidir. Amacınız, ekibinizin günlük çalışma şeklini değiştirmeden dayanıklılık ve geçmiş elde etmek olduğunda yedeklemeyi kullanın.

Bir dal ve depo yapısı seçme

Önceden alacağınız yapısal kararlar, entegrasyonun daha sonra ne kadar sorunsuz hissettireceğini şekillendirir. İki soru baskın gelir: hangi dal ve kaç depo.

Dal seçimi. Çoğu ekip, standart belirtim için main dalına senkronize olur ve devam eden tasarımlar için özellik dallarını kullanır. Apidog'u bir özellik dalına işaret etmek, belirtim değişikliği üzerinde izole olarak yineleme yapmanıza, bir çekme isteği açmanıza ve inceleme geçtikten sonra birleştirmenize olanak tanır; API tasarımınız kodunuzla aynı dallanma modelini izler. Apidog'u doğrudan main dalına işaret etmek daha basittir ancak inceleme kapısını atlar, bu nedenle küçük ekipler veya düşük riskli değişiklikler için saklayın.

Bir depo mı, çok depo mu? Tek doğru cevap yok, ancak ödünleşimler açık:

• Her API için bir depo, her belirtimin geçmişini temiz tutar ve erişim kontrollerini daraltır. Farklı ekiplerin farklı API'lere sahip olduğu durumlarda doğal bir uyum sağlar.
• Tüm belirtimler için tek bir monorepo, her şeyi merkezileştirir ve API'ler arası arama ve incelemeyi basitleştirir. Tek bir platform ekibinin API yüzeyine sahip olduğu durumlarda iyi çalışır. Sadece dizin düzenini tahmin edilebilir tutun, her modül için bir klasör, böylece yedeklemeler ve senkronizasyonlar çakışmaz.

Bir monorepo kullanıyorsanız, her modüle kendi yolunu verin. Bu, otomatik yedeklemeleri düzenli tutar ve belirtim farklarını incelemede okunması kolay hale getirir.

Ekip izinleri ve erişim

Git entegrasyonu kimlik bilgilerine dokunduğu için, kimin ne yapabileceği konusunda bilinçli olmak önemlidir. İzinler iki yerde bulunur: Apidog içinde ve Git sağlayıcınız içinde.

Apidog içinde, ekip izinleri proje kurulumu sırasında yapılandırılır. Bağlı depoya kimlerin senkronize edip push yapabileceğine burada karar verirsiniz. Push haklarını belirtimin sahibi olan kişilerle sınırlayın ve diğer herkesin okumasına izin verin. Bu, API tasarımını sadece görüntüleyen katkıda bulunanlardan kazara yapılan push'ları önler.

Git sağlayıcınız içinde, kimlik bilgisi önemlidir. GitHub ve GitLab için OAuth yetkilendirmesi, onu veren kullanıcının erişimini taşır. Azure DevOps ve genel bağlantılar için kişisel erişim belirteci (token) kimlik bilgisidir, bunu bir sır gibi saklayın. Belirteçleri paylaşılan belgelere yapıştırmayın, yalnızca hedef depolara göre kapsamlandırın ve diğer sırları döndürdüğünüz sıklıkta döndürün. Biri ekipten ayrılırsa, belirtecini iptal edin ve hala aktif olan bir hesap altında yeniden yetkilendirin.

Prensip basittir: entegrasyon, arkasındaki en zayıf belirteç kadar kilitlidir. Kapsamları dar tutun ve sahipliği netleştirin.

Birleştirme çakışmalarını ve sürüklenmeyi yönetme

Apidog gerçek Git geçmişini commit ettiği için, Git'in çakışma modelini ve bunu çözmek için Git'in araçlarını miras alır. Çakışmalar, iki kişi belirtimin aynı kısmını senkronizasyondan önce değiştirdiğinde meydana gelir.

Senaryoyu hayal edin. Apidog'da Order şemasını düzenler ve push yaparsınız. Bir ekip arkadaşı aynı şemayı depo tarafında düzenledi ve ilk push'u o yaptı. Uzlaştırmaya çalıştığınızda, Git YAML üzerinde bir çakışma işaretler, çünkü her iki taraf da çakışan satırları değiştirmiştir. Bu bir Apidog sorunu değil; YAML dosyasında normal bir Git birleştirme çakışmasıdır ve bunu normal yolla çözersiniz.

Çakışmalardan uzak durmak için, push yapmadan önce pull yapın. Kendi değişikliklerinizi commit etmeden önce en son depo durumunu Apidog'a getirmek, çalışma kopyanızı güncel tutar ve iki düzenlemenin çakışabileceği pencereyi daraltır. Bir çakışma meydana geldiğinde, onu herhangi bir birleştirme çakışmasını çözeceğiniz gibi YAML üzerinde çözün: doğru satırları seçin, belgeyi geçerli tutun ve yeniden senkronize edin. Düzenleyicinin canlı doğrulaması burada yardımcı olur; OpenAPI yapısını bozan başarısız bir birleştirme, push yaptıktan sonra değil, hemen ortaya çıkar.

Apidog ve deponun sessizce ayrıldığı sürüklenme, aynı sorunun yavaş versiyonudur. "Şimdi senkronize edildi" göstergesi sizin erken uyarınızdır. Senkronize edildiğini göstermiyorsa, bir şeyler push edilmemiş veya pull edilmemiştir. Bu durumu, boşluk büyümeden önce uzlaştırma için bir uyarı olarak kabul edin.

Sorun Giderme

Çoğu entegrasyon sorunu kimlik doğrulamaya, dal seçimine veya kesintiye uğramış bir senkronizasyona dayanır. Daha derin bir sorun olduğunu varsaymadan önce tabloyu inceleyin.

Yetkilendirme tekrar eden bir tema ise ve genellikle öyledir, kimlik bilgisinin aktif ve doğru şekilde kapsamlandırıldığını onaylayarak başlayın. İptal edilmiş bir belirteç veya eksik bir organizasyon onayı, "çalışmayı durdurdu" raporlarının çoğunu açıklar.

Sıkça Sorulan Sorular

Senkronizasyon tek yönlü mü yoksa iki yönlü mü?

Kullandığınız yeteneğe bağlıdır. Belirtim-Önce Modu iki yönlüdür: düzenlemeleri Git'e push yapar ve depo değişikliklerini Apidog'a geri çekersiniz. Otomatik yedekleme tek yönlüdür: Apidog, her modülün belirtimini zamanlanmış olarak depoya dışa aktarır ve değişiklikleri geri okumaz.

Belirtimlerim nerede saklanıyor?

Bağladığınız Git deposunda. Belirtim-Önce Modu için, OpenAPI belgeniz push yaptığınız dalda bulunur. Otomatik yedekleme için, her modülün dışa aktarılmış OpenAPI/Swagger dosyası yapılandırdığınız depoya commit edilir. Her iki durumda da Git sürümlü kopyayı tutar ve deponun tam kontrolü sizde kalır.

Hangi dala senkronize etmeliyim?

Standart belirtim için main dalını ve devam eden değişiklikler için özellik dallarını kullanın. Bir özellik dalına senkronize etmek, belirtim değişikliğinin bir çekme isteği ve incelemeden geçerek birleşmeden önce ilerlemesini sağlar, bu da kodunuzun Git üzerinden nasıl hareket ettiğini yansıtır.

Belirtecim iptal edilirse ne olur?

Apidog'un yazma erişimi kalmadığı için push'lar başarısız olmaya başlar. Sağlayıcıyı yeniden yetkilendirin veya Azure DevOps ve genel bağlantılar için yeni bir kişisel erişim belirteci oluşturun ve Apidog'da güncelleyin. Kimlik bilgisi geri yüklendiğinde, senkronizasyon ve yedekleme normal şekilde devam eder.

Sonuç

Apidog Git entegrasyonu size iki tamamlayıcı araç sunar: belirtimi kod olarak gören ekipler için Belirtim-Önce Modu aracılığıyla iki yönlü senkronizasyon ve yalnızca sürümlü bir güvenlik ağı isteyen herkes için otomatik modül başına yedekleme. Her ikisi de GitHub, GitLab ve Azure DevOps genelinde çalışır, böylece yeni bir sağlayıcı benimsemek yerine zaten kullandığınızı bağlarsınız.

Hedefinize uyan yeteneği seçin. Her belirtim değişikliğinde inceleme ve geçmiş istiyorsanız, Belirtim-Önce Modu'nu kurun ve commit-ve-push ritmini benimseyin. İş akışınızı değiştirmeden dayanıklılık istiyorsanız, yedeklemeyi açın ve gece push'unun bunu halletmesine izin verin. Birçok ekip ikisini de kullanır. Bağlamaya hazır olduğunuzda, sağlayıcınızı bağlayın, bir projeyi bir depoya ve dala işaret edin ve API belirtimlerinizin, işinizin geri kalanının zaten bulunduğu yerde yaşamasını sağlayın.