Git Tabanlı API İş Akışı Nedir ve Nasıl Oluşturulur?

Kodunuz Git'te yaşıyor. CI işlem hatlarınız, kod incelemeleriniz ve sürüm geçmişiniz Git'te yaşıyor. API spesifikasyonunuz da aynı yerde yaşamalı.

Apidog'u bugün deneyin

Git tabanlı bir API iş akışında OpenAPI tanımınızı kodunuzla aynı depoda tutarsınız. Spesifikasyonu düz bir YAML veya JSON dosyası olarak düzenler, commit eder ve pull request sürecinden geçirirsiniz. Ayrı bir bulut veritabanı, manuel export/import veya ikinci bir doğruluk kaynağı yoktur.

💡 Apidog bunu Spec-First Modu ile destekler. API'nizi IDE tarzı bir düzenleyicide tasarlayabilir, ardından ham OpenAPI dosyalarını GitHub veya GitLab ile iki yönlü senkronize edebilirsiniz. Bu yazıda Git tabanlı API iş akışını, bulut kilitli spesifikasyonların neden sorun çıkardığını ve Spec-First Modu'nun nasıl kurulacağını adım adım göreceksiniz.

Git tabanlı bir API iş akışı ne anlama geliyor?

Git tabanlı bir API iş akışı, API spesifikasyonunuzu kod gibi yönetmeniz demektir. OpenAPI dosyası servislerinizin yanında bir Git deposunda bulunur. Her değişiklik bir commit olur. Her commit'in yazarı, mesajı ve diff'i vardır.

Bu yaklaşım size pratikte üç şey sağlar:

• Sürüm geçmişi: Bir endpoint'i kimin, ne zaman ve neden değiştirdiğini görebilirsiniz. git blame OpenAPI dosyanız üzerinde çalışır.
• Branch ve pull request incelemesi: Spesifikasyon değişiklikleri de kod değişiklikleri gibi PR'dan geçer. İnceleyiciler merge öncesinde satır satır diff görür.
• Tek doğruluk kaynağı: main branch'indeki OpenAPI dosyası API sözleşmesidir. Dokümantasyon, mock servisler, contract testleri ve kod üreticiler aynı dosyadan beslenir.

Spec-first yaklaşımın temel fikri budur: önce sözleşme tanımlanır, uygulama bu sözleşmeyi takip eder. Daha geniş arka plan için spesifikasyon odaklı API geliştirme kılavuzuna bakabilirsiniz.

Alternatif yaklaşımda spesifikasyon tescilli bir bulut aracının içinde saklanır. Küçük ekiplerde bu yeterli görünebilir; ancak ekip ve süreç büyüdükçe sorunlar belirginleşir.

Bulut kilitli API spesifikasyonlarının sorunu

Birçok API tasarım aracı spesifikasyonu kendi veritabanında tutar. Siz UI üzerinden düzenleme yaparsınız; ancak "dosya" sandığınız şey aslında başka bir sistemdeki kayıttır.

Bu yapı birkaç noktada kırılır:

1. İnceleme iki farklı yerde yapılır

Kod değişiklikleri GitHub veya GitLab PR'larından geçer. Spesifikasyon değişiklikleri ise ayrı bir araçta, ayrı yorumlarla ve ayrı geçmişle incelenir.

Sonuç:

• İnceleyiciler bağlam değiştirir.
• Kod ve spesifikasyon onayları senkronize kalmaz.
• Merge edilen kodun hangi API sözleşmesine karşılık geldiği belirsizleşir.

2. Diff görünürlüğü zayıflar

Spesifikasyon bulut veritabanında yaşadığında PR içinde temiz bir YAML/JSON diff'i göremezsiniz. "Tasarımın v3 sürümü" onaylanır; ancak hangi endpoint, response veya schema'nın değiştiği net değildir.

Git tabanlı dosyada ise değişiklik doğrudan görünür:

 responses:
   "200":
     description: Order found
+  "404":
+    description: Order not found

3. Export/import süreci hata üretir

CI'da lint, contract test veya kod üretimi çalıştırmak için spesifikasyonu dışa aktarmanız gerekir. Tipik akış şöyle olur:

1. Bulut aracından OpenAPI dosyasını export edin.
2. Dosyayı repoya commit edin.
3. Bu sırada kimsenin bulut kopyasını değiştirmediğinden emin olmaya çalışın.
4. CI'da export edilen dosyayı kullanın.

Bu artık iki doğruluk kaynağı demektir: buluttaki spesifikasyon ve Git'teki export edilmiş dosya.

4. Otomasyon ek adımlara bağımlı olur

Linters, contract testleri ve code generator'lar diskte bir dosya ister. Spesifikasyon Git'te dosya olarak durmuyorsa her CI çalışmasında önce "spesifikasyonu getir" adımı gerekir.

API spesifikasyonunuzu kod olarak ele aldığınızda bu adımlar ortadan kalkar. Dosya spesifikasyondur. Git geçmişi tutar. CI aynı dosyayı kullanır. Bu prensibi API spesifikasyonunu kod olarak ele alma kılavuzunda daha ayrıntılı ele alıyoruz.

Apidog Spec-First Modu nasıl çalışır?

Spec-First Modu, API spesifikasyonunu Git üzerinden yöneten ekipler için tasarlanmıştır. API'yi ham YAML veya JSON dosyaları olarak düzenlersiniz. Apidog bu dosyaları Git deponuzla iki yönlü senkronize tutar.

Temel akış şudur:

1. Git deponuzu Apidog'a bağlayın.
2. OpenAPI dosyanızı Apidog düzenleyicisinde açın.
3. YAML/JSON üzerinde değişiklik yapın.
4. Değişiklikleri commit edin.
5. Git'e push edin.
6. CI ve ekip arkadaşlarınız aynı spesifikasyonu kullansın.

IDE tarzı OpenAPI düzenleyici

Spec-First Modu'nda spesifikasyonu form tabanlı bir arayüz yerine kod düzenleyicide yazarsınız. Düzenleyici şu özellikleri sağlar:

• YAML ve JSON için sözdizimi vurgulama
• OpenAPI ve Swagger şemalarına karşı doğrulama
• OpenAPI anahtar kelimeleri, tipleri ve referansları için otomatik tamamlama
• Dosyadaki path, operation ve schema yapılarını hızlı gezme

Bu sayede dosyanın tamamı sizin kontrolünüzde kalır. Gizli alanlar veya sadece UI'a ait metadata yoktur.

Ham YAML/JSON dosyalarıyla çalışma

Spec-First Modu'nda düzenlediğiniz şey doğrudan Git'e commit edilen dosyadır. Örneğin küçük bir OpenAPI parçası şöyle olabilir:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.2.0

paths:
  /orders/{orderId}:
    get:
      summary: Get an order by ID
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - pending
            - shipped
            - delivered

Bu dosya repoya iner. Üzerinde yaptığınız değişiklik diff olarak görünür. Commit edilen şey de tam olarak düzenlediğiniz içeriktir.

Otomatik ayrıştırılan gezilebilir taslak

Uzun OpenAPI dosyalarında gezinmek zor olabilir. Spec-First Modu, yazdığınız dosyayı ayrıştırır ve sol kenar çubuğunda gezilebilir bir taslak oluşturur.

Bu taslakta şunları görebilirsiniz:

• Paths
• Operations
• Schemas
• Referans verilen yapılar

Böylece yüzlerce satır kaydırmadan doğrudan ilgili endpoint'e veya schema'ya gidebilirsiniz.

İki yönlü Git senkronizasyonu

Spec-First Modu Git sağlayıcınıza bağlanır ve değişiklikleri iki yönde senkronize eder.

Desteklenen yapı:

• GitHub ile doğrudan senkronizasyon
• GitLab ile doğrudan senkronizasyon
• Azure DevOps için Git Bağlantısı üzerinden destek

Tipik kullanım:

1. Ekip arkadaşlarınızın Git'e gönderdiği değişiklikleri içeri çekin.
2. Apidog düzenleyicisinde OpenAPI dosyasını düzenleyin.
3. Aynı branch'e commit edin.
4. Değişiklikleri geri push edin.

Bu şekilde repo ve Apidog çalışma alanı aynı durumda kalır.

Commit, push ve senkronizasyon durumunu izleme

Git işlemleri için Apidog'dan ayrılmanız gerekmez. Değişiklikleri hazırlayabilir, commit mesajı yazabilir ve push edebilirsiniz.

İyi commit mesajı örnekleri:

getOrder endpointine 404 yanıtı ekle

Order schema status enum değerlerini güncelle

POST /orders request body şemasını düzelt

Kötü commit mesajı örnekleri:

update

spec değişti

fix

Push sonrası senkronizasyon durumu göstergesi uzak branch ile yerel düzenlemelerin eşleşip eşleşmediğini gösterir. Başarılı push sonrasında "Az önce senkronize edildi" durumunu görürsünüz. Push öncesi vazgeçerseniz gönderilmemiş düzenlemeleri iptal edip son senkronize duruma dönebilirsiniz.

GitHub odaklı ayrı bir örnek için OpenAPI spesifikasyonunu GitHub ile senkronize etme kılavuzuna bakabilirsiniz.

Kurulum kılavuzu

Aşağıdaki adımlar boş veya mevcut bir repodan senkronize edilmiş bir OpenAPI spesifikasyonuna geçmek için kullanılabilir. Tam referans için Spec-First Modu belgelerine bakabilirsiniz.

1. Repodan proje oluşturun

Apidog'da yeni bir Spec-First projesi başlatın ve Git sağlayıcınızı bağlayın.

Seçmeniz gerekenler:

• Git sağlayıcısı
• API spesifikasyonunu içeren repo
• İzlenecek branch, genellikle main
• OpenAPI YAML/JSON dosyası veya dosyaları

Apidog mevcut spesifikasyon dosyalarını düzenleyiciye çeker.

2. OpenAPI dosyasını düzenleyin

Düzenleyicide OpenAPI dosyanızı açın. Örneğin:

• Yeni endpoint ekleyin
• Response şemasını düzeltin
• Eksik hata yanıtı ekleyin
• Schema alanlarını güncelleyin
• Operation ID'leri standartlaştırın

Yazarken sözdizimi vurgulama, doğrulama ve otomatik tamamlama size yardımcı olur. Dosya değiştikçe sol kenar çubuğundaki taslak da güncellenir.

3. Değişen dosyaları kontrol edin

Apidog son senkronizasyondan bu yana değişen dosyaları gösterir.

Takip edebileceğiniz durumlar:

• Değiştirilen dosyalar
• Eklenen dosyalar
• Silinen dosyalar

Bu adım, commit'e neyin gireceğini görmenizi sağlar.

4. Commit mesajı yazın

Değişikliği açıkça anlatan bir commit mesajı yazın.

Örneğin:

GET /orders/{orderId} için 404 response ekle

Bu, aşağıdaki mesajdan daha kullanışlıdır:

spesifikasyonu güncelle

Çünkü PR incelemesinde ve Git geçmişinde değişikliğin amacı hemen anlaşılır.

5. Push edin

Commit'i izlenen branch'e gönderin. Bu noktadan sonra:

• Ekip arkadaşlarınız yeni spesifikasyonu görebilir.
• CI pipeline aynı dosyayı kullanabilir.
• Pull request süreciniz normal şekilde çalışır.

6. Senkronizasyon durumunu doğrulayın

Push sonrası durum göstergesini kontrol edin. "Az önce senkronize edildi" ifadesini gördüğünüzde yerel düzenlemeleriniz ile uzak branch eşleşir.

Tam döngü şu hale gelir:

pull -> düzenle -> commit -> push -> doğrula

Export adımı yoktur. İkinci doğruluk kaynağı yoktur.

Spec-First ve Design-First modu

Apidog iki farklı çalışma şeklini destekler. Fark, spesifikasyonun nerede yaşadığı ve nasıl düzenlendiğidir.

Özellik	Spec-First Modu (beta)	Design-First Modu
Spesifikasyon depolama	Git'teki ham YAML/JSON dosyaları	Apidog bulut projesi
Birincil düzenleyici	IDE tarzı kod düzenleyici	Görsel, form tabanlı UI
Sürüm kontrolü	Git commit'leri, branch'ler ve diff'ler	Apidog geçmişi ve branch'leri
İki yönlü Git senkronizasyonu	Evet: GitHub, GitLab, Azure DevOps	Export/import üzerinden
En uygun kullanım	Git merkezli ekipler	Görsel iş akışını tercih eden ekipler

Hiçbir mod her durumda daha iyi değildir. Seçim ekibinizin çalışma biçimine bağlıdır.

Spec-First Modu şu ekipler için daha uygundur:

• API sözleşmesini PR üzerinden inceleyenler
• CI'da OpenAPI lint, contract test veya code generation çalıştıranlar
• Spesifikasyonu doğrudan YAML/JSON olarak düzenleyenler
• Git geçmişi ve diff görünürlüğü isteyenler

Design-First Modu şu ekipler için daha uygun olabilir:

• Ham OpenAPI yazmak istemeyenler
• Görsel form tabanlı tasarımı tercih edenler
• Mühendis olmayan paydaşların da API tasarımına yoğun şekilde katıldığı ekipler

Ne zaman Spec-First Modu kullanılır?

Spec-First Modu'nu şu durumlarda kullanın:

• Spesifikasyonunuz pull request ve kod incelemesinden geçmeli.
• API sözleşmeniz için gerçek commit geçmişi istiyorsunuz.
• git blame ile endpoint değişikliklerini izlemek istiyorsunuz.
• CI pipeline diskte bir OpenAPI dosyasına ihtiyaç duyuyor.
• Lint, contract test veya code generation çalıştırıyorsunuz.
• Birden fazla mühendis aynı spesifikasyonu düzenliyor.
• Temiz, merge edilebilir YAML/JSON diff'leri görmek istiyorsunuz.
• Araçtan export edip başka araca import etmekten kaçınmak istiyorsunuz.

Görsel, bulut öncelikli yaklaşımı ise şu durumda tercih edin:

• Ekip ham OpenAPI yazmadan API tasarlıyor.
• Spesifikasyonu teknik olmayan kullanıcılar yönetiyor.
• Form tabanlı düzenleyici iş akışınıza daha uygun.

Örnek CI kullanım fikri

Spesifikasyon Git'te dosya olarak durduğunda CI'da doğrudan kullanabilirsiniz. Örneğin basit bir pipeline mantığı şöyle olabilir:

name: API Spec Check

on:
  pull_request:
    paths:
      - "openapi/**/*.yaml"
      - "openapi/**/*.json"

jobs:
  validate-openapi:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: OpenAPI dosyalarını kontrol et
        run: |
          echo "OpenAPI validasyon, lint veya contract test adımlarınızı burada çalıştırın"

Bu örnek belirli bir araca bağlı değildir. Ana fikir şudur: spesifikasyon repoda olduğu için CI onu ek export adımı olmadan okuyabilir.

SSS

Git tabanlı bir API iş akışı nedir?

Git tabanlı API iş akışı, OpenAPI spesifikasyonunuzu Git deposunda dosya olarak saklamanız ve her değişikliği commit, branch ve pull request süreçleriyle yönetmenizdir. Spesifikasyon, uygulama kodunuzla aynı inceleme ve sürüm kontrolü sürecinden geçer.

Apidog Spec-First Modu GitHub ve GitLab'i destekliyor mu?

Evet. Spec-First Modu GitHub ve GitLab ile doğrudan iki yönlü senkronize olur. Azure DevOps, Git Bağlantısı aracılığıyla desteklenir. Repo bağlar, branch seçer ve Apidog ile uzak depo arasında senkronizasyonu sürdürürsünüz.

OpenAPI dosyalarını ham YAML veya JSON olarak düzenleyebilir miyim?

Evet. Spec-First Modu ham YAML ve JSON dosyaları için IDE tarzı bir düzenleyici sunar. Sözdizimi vurgulama, OpenAPI/Swagger şema doğrulama ve otomatik tamamlama özellikleriyle dosyayı doğrudan düzenleyebilirsiniz.

Spec-First ve Design-First modları arasındaki fark nedir?

Spec-First Modu, spesifikasyonunuzu Git'te ham YAML/JSON dosyaları olarak tutar ve iki yönlü Git senkronizasyonu sağlar. Design-First Modu, spesifikasyonu Apidog bulut projesinde tutar ve görsel, form tabanlı bir düzenleyici kullanır. İş akışınız zaten Git üzerine kuruluysa Spec-First daha uygundur.

Sonuç

Git tabanlı API iş akışı, uygulama kodunuz ile API sözleşmeniz arasındaki ayrımı azaltır. OpenAPI spesifikasyonu bir dosya olur, dosya commit edilir ve commit mevcut inceleme sürecinizden geçer.

Apidog Spec-First Modu bu akış için IDE tarzı OpenAPI düzenleyici, gezilebilir dosya taslağı ve iki yönlü Git senkronizasyonu sunar. Ham YAML veya JSON'u düzenler, anlamlı bir commit mesajıyla gönderir ve durumun "Az önce senkronize edildi" olduğunu doğrularsınız.

Spec-First Modu'nu deneyin ve API spesifikasyonunuzu Git iş akışınıza taşıyın.