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

OpenAPI belgeniz bir Git deposunda duruyor ama spesifikasyonu ayrı bir API istemcisinde düzenliyorsanız, tipik sorunları bilirsiniz: YAML kopyala-yapıştır, dosyaya başka biri dokunmuş mu kontrol et, içe aktarma sırasında alan kaybolmadığından emin ol. Bu süreç hem zaman kaybettirir hem de özellikle hızlı iterasyon gereken ekiplerde senkronizasyon hatalarına açıktır.

Apidog'u bugün deneyin

Bu kılavuzda OpenAPI spesifikasyonunuzu Apidog’un Spec-First Modu ile GitHub’a nasıl senkronize edeceğinizi adım adım göreceksiniz. Amaç basit: depodaki spesifikasyon ile Apidog’daki düzenleyici aynı kaynağı kullansın; manuel dışa aktarma, içe aktarma veya kopyalama gerekmemesi.

Aynı akış GitLab için de geçerlidir.

İki yönlü senkronizasyon ne sağlar?

İki yönlü senkronizasyon, OpenAPI belgesindeki değişikliklerin Git deposu ile Apidog arasında otomatik olarak iki yönde akmasıdır.

• Apidog’dan Git’e: Apidog’da OpenAPI belgesini düzenleyip commit ettiğinizde değişiklik seçtiğiniz dala normal bir Git commit’i olarak gönderilir.
• Git’ten Apidog’a: Bir ekip arkadaşı veya siz IDE üzerinden aynı dala değişiklik gönderdiğinizde Apidog bu değişikliği geri çeker ve düzenleyici güncel depo durumunu yansıtır.

Bu modelde depo tek doğruluk kaynağıdır. Apidog ise bu kaynağın üzerinde çalışan görsel ve kod odaklı bir OpenAPI düzenleyicisidir.

Ön koşullar

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

• Apidog masaüstü uygulaması veya web sürümü
• Oturum açılmış bir Apidog hesabı
• OpenAPI belgesi içeren veya yazma erişiminizin olduğu bir GitHub ya da GitLab deposu
• Spec-First Modu etkin bir Apidog projesi
• Senkronize etmek istediğiniz dalda yazma izni

Azure DevOps da Git Bağlantısı aracılığıyla desteklenir.

Salt okunur erişim ile depodan çekebilirsiniz, ancak değişiklikleri geri itemezsiniz.

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

İlk olarak Apidog’un Git sağlayıcınıza erişebilmesi gerekir.

1. Apidog’u açın.
2. Yeni proje oluştururken Spec-First Modu seçeneğini kullanın.
3. Kaynak olarak GitHub veya GitLab seçin.
4. Yetkilendir butonuna tıklayın.
5. Açılan OAuth ekranında Apidog’a gerekli depo erişimlerini verin.

GitHub kullanıyorsanız erişimi tüm hesaba değil, yalnızca belirli depolara verebilirsiniz. Güvenlik açısından genellikle önerilen yaklaşım budur.

Yetkilendirme tamamlandığında Apidog’a geri yönlendirilirsiniz. Bu işlemi her sağlayıcı için yalnızca bir kez yapmanız yeterlidir; sonraki projelerde aynı bağlantı yeniden kullanılabilir.

Tam akış için Spec-First Modu belgelerine bakabilirsiniz.

Adım 2: Depo, dal ve OpenAPI dosyasını seçin

Git sağlayıcısı bağlandıktan sonra Apidog’u gerçek OpenAPI dosyanıza yönlendirin.

1. OpenAPI dosyanızı içeren depoyu seçin.
2. Senkronize edilecek dalı seçin. Genellikle main, master veya aktif geliştirme dalı kullanılır.
3. OpenAPI dosyasının yolunu doğrulayın:
   • openapi.yaml
   • openapi.yml
   • docs/openapi.yaml
   • specs/api.yaml
4. Projeyi oluşturun.

Apidog seçilen daldan spesifikasyonu alır ve düzenleyicide açar. Sol kenar çubuğunda endpoint’ler, şemalar ve diğer OpenAPI bileşenleri gezilebilir bir yapı olarak görünür.

Bu noktadan sonra Apidog’da gördüğünüz belge, deponuzdaki OpenAPI spesifikasyonudur.

Adım 3: OpenAPI YAML dosyasını düzenleyin

Spec-First Modu, ham OpenAPI YAML üzerinde çalışmanıza izin verir. Düzenleyici şu özellikleri sağlar:

• Sözdizimi vurgulama
• Satır içi doğrulama
• Otomatik tamamlama
• OpenAPI yapısının sol menüde canlı güncellenmesi

Örneğin spesifikasyona basit bir health check endpoint’i ekleyelim:

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

Bu değişikliği yazarken Apidog iki şeyi aynı anda yapar:

1. Yeni /health operasyonunu sol taraftaki OpenAPI ağacına ekler.
2. YAML girintisi, eksik responses bloğu veya bozuk $ref gibi hataları satır içinde işaretler.

Bu sayede hatalı bir OpenAPI dosyasını CI pipeline’da fark etmek yerine, düzenleme sırasında yakalayabilirsiniz.

OpenAPI dosyalarının Git geçmişi, diff ve branch akışlarıyla nasıl yönetileceğini daha detaylı görmek isterseniz Git ile OpenAPI sürüm kontrolü kılavuzuna bakabilirsiniz.

Adım 4: Değişikliği commit edin ve GitHub’a itin

Düzenleme tamamlandığında değişikliği doğrudan Apidog üzerinden GitHub’a gönderebilirsiniz.

1. Apidog’daki Git veya kaynak kontrol panelini açın.
2. Değişiklikleri gözden geçirin.
3. Commit mesajı yazın.

Örnek:

/health uç noktasını ekle

1. Commit Et ve İt seçeneğine tıklayın.

Apidog seçtiğiniz dala normal bir Git commit’i oluşturur ve uzak depoya iter. GitHub’da depo geçmişini açtığınızda commit’i ilgili dalda görebilirsiniz.

Henüz push etmeden fikrinizi değiştirdiyseniz, itilmemiş düzenlemeleri atabilirsiniz. Commit işlemi yapılana kadar değişiklikler uzak depoya gönderilmez.

Adım 5: Senkronizasyon durumunu kontrol edin

Apidog, düzenleyici ile uzak depo arasındaki durumu gösteren bir senkronizasyon göstergesi sunar.

Başarılı bir push sonrasında gösterge genellikle şu anlama gelen bir durum gösterir:

Az önce senkronize edildi

Bu, Apidog’daki OpenAPI belgesi ile uzak daldaki dosyanın aynı durumda olduğunu belirtir.

Zaman geçtikçe durum güncellenir:

5 dakika önce senkronize edildi

Başka biri aynı dala değişiklik gönderirse Apidog bu değişikliği çeker ve düzenleyicide güncel durumu yansıtır.

Gösterge bekleyen, güncel olmayan veya çakışmalı bir durum gösteriyorsa devam etmeden önce uzak değişiklikleri çekmeniz ya da çakışmayı çözmeniz gerekir.

Sorun giderme

Yetkilendirme süresi dolduysa

Push işlemleri izin hatasıyla başarısız oluyorsa Git sağlayıcısı tarafında token iptal edilmiş veya süresi dolmuş olabilir.

Çözüm:

1. Apidog’da Git sağlayıcı bağlantısını yeniden yetkilendirin.
2. Gerekirse GitHub veya GitLab OAuth izinlerini kontrol edin.
3. Depoya yazma izniniz olduğundan emin olun.

Yanlış dala commit ediyorsanız

Commit beklediğiniz dala düşmüyorsa proje oluştururken seçilen dalı kontrol edin.

Özellikle korumalı main dallarında doğrudan push reddedilebilir. Bu durumda:

• Ayrı bir feature branch kullanın.
• Pull request akışına geçin.
• Dal koruma kurallarını gözden geçirin.

Merge conflict oluşursa

Siz Apidog’da düzenleme yaparken bir ekip arkadaşı aynı OpenAPI dosyasının aynı bölümünü değiştirmiş olabilir.

Çözüm:

1. Uzak değişiklikleri çekin.
2. Çakışan YAML bölümlerini düzeltin.
3. OpenAPI doğrulamasını kontrol edin.
4. Tekrar commit edip push edin.

OpenAPI dosyası düz metin olduğu için çakışmalar standart Git çakışmaları gibi çözülür.

Doğrulama hataları görünüyorsa

Apidog geçersiz YAML veya eksik OpenAPI alanlarını satır içinde işaretler. Commit etmeden önce şu noktaları kontrol edin:

• YAML girintisi doğru mu?
• Her operasyon için responses alanı var mı?
• $ref yolları geçerli mi?
• schema yapıları doğru seviyede mi?
• HTTP metodları doğru yazılmış mı?

Temiz bir OpenAPI spesifikasyonu; dokümantasyon, mock server ve test süreçlerinin daha güvenilir çalışmasına yardımcı olur.

Sıkça Sorulan Sorular

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

Evet. Spec-First Modu GitHub ve GitLab’ı doğrudan destekler. Azure DevOps ise Git Bağlantısı aracılığıyla kullanılabilir.

Akış aynıdır:

1. Sağlayıcıyı bağla
2. Depoyu ve dalı seç
3. OpenAPI dosyasını düzenle
4. Commit et
5. Push et

Yalnızca yetkilendirme ekranı sağlayıcıya göre değişir.

Ben Apidog’da çalışırken ekip arkadaşım depodaki spesifikasyonu değiştirirse ne olur?

Apidog iki yönlü senkronizasyon kapsamında uzak değişikliği düzenleyiciye çeker.

Değişiklikler dosyanın farklı bölümlerindeyse temiz şekilde birleşir. Aynı YAML bölümünde değişiklik yapıldıysa standart Git çakışması çözmeniz gerekir.

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

Evet. Commit Et ve İt seçeneğine tıklayana kadar değişiklikler uzak depoya gönderilmez.

İtilmemiş düzenlemeleri atarak belgeyi son senkronize edilmiş duruma geri döndürebilirsiniz.