OpenAPI Spesifikasyonunu GitHub'a İki Farklı Yöntemle Nasıl Senkronize Edersiniz?

OpenAPI belgeniz bir Git deposunda bulunuyor ancak onu bir API istemcisinde düzenliyorsanız, sürtüşmeyi zaten biliyorsunuzdur: YAML'yi kopyalayın, geri yapıştırın, umarım başkası dosyaya dokunmamıştır ve içe aktarmanın sessizce bir alanı düşürmediğini umun. Bir spesifikasyonu ve bir depoyu manuel olarak senkronize tutmak, tam da acele ettiğinizde bozulan bir angarya türüdür.

Bu kılavuz, OpenAPI spesifikasyonunuzu Apidog'un Spec-First Modu ile GitHub'a nasıl senkronize edeceğinizi gösterir, böylece deponuzdaki spesifikasyon ve düzenleyicinizdeki spesifikasyon, sürekli uzlaştırdığınız iki kopya yerine aynı şey olarak kalır. Bir sağlayıcıyı bağlayacağız, doğrudan bir depodan bir proje açacağız, YAML'yi düzenleyeceğiz ve değişikliği tek seferde GitHub'a geri göndereceğiz. Aynı adımlar GitLab için de geçerlidir.

Hadi başlayalım.

İki yönlü senkronizasyon aslında ne anlama geliyor

İki yönlü senkronizasyon, arada herhangi bir dışa aktarma adımı olmaksızın, düzenlemelerin otomatik olarak her iki yönde de akması anlamına gelir.

• Apidog'dan Git'e: Apidog'da OpenAPI belgesini düzenleyip onayladığınızda, değişiklik seçtiğiniz dala normal bir Git taahhüdü olarak deponuza itilir.
• Git'ten Apidog'a: Bir ekip arkadaşı (veya siz, IDE'nizden) o dala bir değişiklik ittiğinde, Apidog onu geri çeker, böylece düzenleyiciniz depodaki gerçek durumu yansıtır.

Depo, tek doğruluk kaynağıdır. Apidog, bunun üzerinde zengin bir düzenleyicidir. Git-native API iş akışının ardındaki tüm fikir budur: spesifikasyon, belirli aralıklarla anlık görüntü dışa aktaran bir araçta durmak yerine, kod tabanınızdaki diğer dosyalar gibi sürüm kontrolü yapılır, incelenir ve geçmişi takip edilir.

Ön Koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

• Apidog yüklü (masaüstü uygulaması veya web), oturum açmış.
• Halihazırda bir OpenAPI belgesi içeren veya yazma erişiminizin olduğu bir GitHub veya GitLab deposu. Azure DevOps, Git Bağlantısı aracılığıyla da desteklenmektedir.
• Spec-First Modu (beta) etkinleştirilmiş. Bu mod, projenizi Apidog'un kendi depolaması yerine bir Git deposu üzerinde ince bir katmana dönüştürür.

Senkronize etmek istediğiniz dalda yazma iznine sahip olmanız gerekir. Salt okunur erişim, çekmenize izin verir ancak itmenize izin vermez.

Adım 1: Git sağlayıcınızı bağlayın

Öncelikle, Apidog'un sağlayıcınızla iletişim kurmasına izin verin.

1. Apidog'u açın ve Spec-First Modu'nu seçerek yeni bir proje oluşturun.
2. Bir kaynak seçmeniz istendiğinde, sağlayıcınızı, GitHub veya GitLab'i seçin.
3. Yetkilendir'e tıklayın. Tarayıcınız sağlayıcının OAuth ekranını açar.
4. Apidog'a senkronize etmek istediğiniz depolara erişim izni verin. GitHub'da bunu tüm hesabınız yerine belirli depolara göre ayarlayabilirsiniz.

Yetkilendirme tamamlandığında, sağlayıcı bağlı olarak Apidog'a geri yönlendirilirsiniz. Bunu her sağlayıcı için yalnızca bir kez yaparsınız, gelecekteki projeler bu bağlantıyı yeniden kullanır.

Azure DevOps'u Git Bağlantısı aracılığıyla dahil eden bu akışın tam referansı için Spec-First Modu belgelerine bakın.

Adım 2: Bir depodan ve daldan proje oluşturun

Şimdi Apidog'u gerçek spesifikasyona yönlendirin.

1. Sağlayıcı bağlıyken, OpenAPI dosyanızı tutan depoyu seçin.
2. Senkronize edilecek dalı seçin, genellikle main. Bu, taahhütlerinizin düşeceği dal ve Apidog'un gelen değişiklikleri izleyeceği daldır.
3. Apidog sorarsa OpenAPI belgesinin yolunu onaylayın (örneğin depo kökünde openapi.yaml veya docs/ altında).
4. Projeyi oluşturun.

Apidog, spesifikasyonu o daldan klonlar ve açar. Sol kenar çubuğu, Apidog belgeyi gezilebilir bir taslağa ayrıştırdığı için uç noktalarınız ve şemalarınızla dolar. Artık deponun spesifikasyonuna canlı olarak bakıyorsunuz.

Adım 3: OpenAPI YAML'nizi kod düzenleyicisinde düzenleyin

Spec-First Modu, ham OpenAPI YAML için sözdizimi vurgulama, satır içi doğrulama ve otomatik tamamlama özelliklerine sahip bir IDE tarzı düzenleyici sunar. OpenAPI'yi doğrudan yazarsınız; Apidog, siz yazarken görsel taslağı güncel tutar.

Küçük bir uç nokta ekleyelim. Bir durum kontrolü istediğinizi varsayalım:

paths:
 /health:
 get:
 summary: Servis durum kontrolü
 operationId: getHealth
 responses:
 '200':
 description: Servis ayakta
 content:
 application/json:
 schema:
 type: object
 properties:
 status:
 type: string
 example: ok

Siz yazdıkça iki şey olur. Sol kenar çubuğu taslağı otomatik olarak ayrıştırır, böylece yeni /health işleminiz hemen ağaçta görünür. Ve doğrulayıcı, bir eksik responses bloğu, kötü bir $ref, bir girinti hatası gibi sorunları, siz taahhüt etmeden önce satır içinde işaretler. YAML yanlış biçimlendirilmişse, daha sonra başarısız bir pipeline'da keşfetmek yerine altı çizili olarak görürsünüz.

Sürüm kontrolü de burada kendini gösterir. Spesifikasyon üzerinde diff'lerin ve geçmişin nasıl oynandığına dair daha derin bir inceleme isterseniz, Git ile OpenAPI sürüm kontrolü hakkındaki kılavuz size yol gösterecektir.

Adım 4: Taahhüt et ve it

Düzenleme doğru göründüğünde, GitHub'a gönderin.

1. Taahhüt panelini açın (projenin Git/kaynak kontrol alanı).
2. Değişikliği gözden geçirin. Apidog, senkronize edilmiş sürüme göre neyin değiştirildiğini gösterir.
3. Bir taahhüt mesajı yazın, herhangi bir taahhüt gibi ele alın: /health uç noktasını ekle.
4. Taahhüt Et ve İt'e tıklayın.

Apidog, seçtiğiniz dala taahhütte bulunur ve uzak depoya iter. GitHub'daki deponuzu açın ve taahhüdü dal geçmişinde, beklendiği gibi yazılmış, tam olarak OpenAPI dosyasını etkileyecek şekilde göreceksiniz.

İtmeden önce fikrinizi mi değiştirdiniz? Belgeyi son senkronize edilmiş duruma geri döndürmek için itilmemiş düzenlemeleri atabilirsiniz. Siz taahhüt edene kadar hiçbir şey Apidog'dan çıkmaz, bu nedenle yerel deneyler yerel kalır.

Adım 5: Senkronizasyon durumunu doğrulayın

Apidog, her zaman nerede olduğunuzu bilmeniz için bir senkronizasyon göstergesi gösterir.

Başarılı bir itme işleminden sonra, gösterge "Az önce senkronize edildi" yazar. Bu, düzenleyicinin ve uzak dalın aynı belgeyi tuttuğuna dair onayınızdır. Zaman geçtikçe güncellenir ("5 dakika önce senkronize edildi") ve başka biri ittiğinde, Apidog değişikliği çeker ve uzlaştırdıktan sonra göstergeyi sıfırlar.

Gösterge bekleyen veya güncel olmayan bir durumu gösteriyorsa, yerel kopyanın ve uzaktaki kopyanın farklılaştığını, devam etmeden önce çekmeniz veya çözmeniz gerektiğine dair bir ipucu olduğunu söyler.

Sorun Giderme

Bazı şeyler ilk başta insanları şaşırtır.

• Yetkilendirme süresi doldu veya iptal edildi. İtmeler bir izin hatasıyla başarısız olmaya başlarsa, 1. Adımdan yetkilendirmeyi yeniden çalıştırın. Tokenlar sağlayıcı tarafında iptal edilebilir veya süresi dolabilir.
• Yanlış dal. Çekme istekleri gerektiren korumalı bir main dalına itmek reddedilecektir. Ya bir has dalına göre senkronize edin ya da dalın koruma kurallarını ayarlayın. 2. Adımda seçilen dalın taahhütlerin düşmesini beklediğiniz yerle eşleştiğinden emin olun.
• Birleştirme çakışmaları. Siz düzenleme yaparken bir ekip arkadaşı aynı dala ittiyse, uzak depo yerel kopyanızın önüne geçmiştir. En son sürümü çekin, çakışan YAML'yi uzlaştırın ve tekrar taahhüt edin. Spesifikasyon düz metin olduğu için, çakışmalar herhangi bir kod çakışması gibi çözülür.
• Doğrulama hataları akışınızı engeller. Apidog geçersiz YAML taahhüt etmenizi engellemez, ancak önce satır içi doğrulayıcının işaretlediği sorunları düzeltmelisiniz. Temiz bir spesifikasyon, oluşturulan belgelerinizi, sahte verilerinizi ve testlerinizi dürüst tutar.

Sıkça Sorulan Sorular

GitHub ile senkronizasyon GitLab ve Azure DevOps ile de çalışır mı?

Evet. Spec-First Modu, GitHub ve GitLab'ı doğrudan, Azure DevOps'u ise Git Bağlantısı aracılığıyla destekler. Bağla-düzenle-taahhüt et-it akışı üçü arasında aynıdır; yalnızca yetkilendirme ekranı sağlayıcıya göre değişir.

Ben Apidog'da çalışırken bir ekip arkadaşı depodaki spesifikasyonu düzenlerse ne olur?

Apidog, iki yönlü senkronizasyonun bir parçası olarak onların değişikliğini düzenleyicinize geri çeker. Sizin düzenlemeleriniz ve onlarınkiler dosyanın farklı kısımlarına dokunuyorsa, temiz bir şekilde birleşirler. Çakışırlarsa, herhangi bir metin dosyasında olduğu gibi standart bir Git çakışmasını çözeceksiniz.

Bir değişikliği GitHub'a ulaşmadan önce geri alabilir miyim?

Evet. Taahhüt Et ve İt'e tıklayana kadar düzenlemeleriniz yereldir. Belgeyi son senkronize edilmiş duruma geri döndürmek için itilmemiş düzenlemeleri at seçeneğini kullanın ve hiçbir şey uzak depoya ulaşmaz.