Git ile OpenAPI Spesifikasyonunu Nasıl Sürüm Kontrol Edersiniz?

OpenAPI belirtiminiz bir sözleşmedir. Bu sözleşme değiştiğinde istemciler bozulabilir, mock veriler güncelliğini yitirebilir ve testler artık geçerli olmayan bir API’ye karşı başarılı görünebilir. Bu yüzden belirtimi kaynak kod gibi yönetin: Git’e ekleyin, dallandırın, PR ile inceleyin ve her değişiklikte doğrulayın.

Apidog'u bugün deneyin

Bu rehber, Git ile OpenAPI sürüm kontrolünü pratik bir iş akışı olarak kurmanıza yardımcı olur. Belirtim dosyasını nereye koyacağınızı, dalları nasıl adlandıracağınızı, PR incelemesinde nelere bakacağınızı, CI doğrulamasını nasıl ekleyeceğinizi ve değişiklikleri Apidog üzerinden nasıl commit/push yapacağınızı adım adım göreceksiniz.

OpenAPI Belirtiminiz için Neden Sürüm Kontrolü Kullanmalısınız?

Bir wiki’de veya paylaşılan sürücüde duran belirtimin güvenilir bir geçmişi yoktur. Örneğin geçen hafta POST /orders payload’unu kimin değiştirdiğini veya neden değiştirdiğini takip etmek zorlaşır.

openapi.yaml dosyasını Git’e aldığınızda şunları kazanırsınız:

• Geçmiş: Her değişiklik yazar, tarih ve commit mesajıyla kayıt altına alınır.
• Blame: git blame openapi.yaml, bir alanı kimin ne zaman eklediğini gösterir.
• Geri alma: Sözleşmeyi bozan bir merge olduysa ilgili commit geri alınabilir.
• İnceleme: Belirtim değişiklikleri PR üzerinden incelenir; dağıtımdan önce ikinci bir göz kontrol eder.

Bu yaklaşım, Git-tabanlı bir API iş akışının temelidir: belirtim kaynak koddur ve kaynak kod Git’te yaşar.

Belirtim Dosyası Repo’da Nerede Bulunmalı?

Basit ve tahmin edilebilir bir yapı seçin. Çoğu ekip tek bir openapi.yaml dosyasını depo köküne veya api/ klasörüne koyar:

my-service/
├── api/
│   └── openapi.yaml
├── src/
└── README.md

Birden fazla ana sürümü paralel sürdürüyor musunuz? Her ana sürüm için ayrı dosya kullanın:

api/
├── api-v1.yaml
└── api-v2.yaml

Bu yapı bozan değişiklikleri izole eder:

• api-v1.yaml mevcut istemciler için stabil kalır.
• api-v2.yaml yeni sözleşme için gelişmeye devam eder.
• Diff’ler küçülür ve PR incelemesi hızlanır.

Belirtimi bu şekilde yönetmek, kod olarak API belirtimi yaklaşımının temelidir.

Önemli nokta: Bir kural seçin ve README’de belgeleyin. Aynı repoda iki farklı dosyanın “ana belirtim” gibi davranması en kötü senaryodur.

Belirtim Değişiklikleri için Dallandırma Stratejisi

OpenAPI için özel bir Git modeli kullanmanız gerekmez. Kodunuzda hangi akış varsa onu kullanın:

1. main üzerinden yeni dal açın.
2. Belirtim değişikliğini yapın.
3. Commit edin.
4. PR açın.
5. CI ve inceleme sonrası merge edin.

Örnek dal adlandırma standardı:

Dal tipi	Desen	Örnek
Yeni uç nokta	api/add-<kaynak>	api/add-refunds
Alan değişikliği	api/change-<kaynak>-<alan>	api/change-order-status
Bozan değişiklik	api/breaking-<açıklama>	api/breaking-v2-auth
Düzeltme / temizlik	api/fix-<açıklama>	api/fix-pagination-schema

api/ öneki, PR’ın API sözleşmesine dokunduğunu hızlıca gösterir. İnceleyiciler ve CI kontrolleri buna göre filtreleme yapabilir.

Bozan değişikliklerde breaking- önekini açıkça kullanın. Bu, ek inceleme ve muhtemelen sürüm artırımı gerektiğini gösterir.

Dalları kısa ömürlü tutun. İki hafta açık kalan bir belirtim dalı, diğer değişikliklerle çakışma ihtimalini artırır. Küçük ve odaklı PR’lar daha kolay merge edilir.

PR’da OpenAPI Değişiklikleri Nasıl İncelenir?

Bir belirtim PR’ı sadece dosya değişikliği değildir; API sözleşmesi değişikliğidir. Bu yüzden gerçek bir inceleme gerektirir.

YAML’ı diff dostu yazın. Tutarlı girinti ve satır başına tek anlamlı özellik kullanın:

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

İnceleme sırasında şu kontrol listesini kullanın:

• Bozan değişiklik var mı?

  • Yeni required alan eklendi mi?
  • Response alanı kaldırıldı mı?
  • Alan adı değişti mi?
  • Enum değeri silindi mi?
  • Parametre tipi değişti mi?

• Geriye dönük uyumluluk korunuyor mu?

  • Yeni opsiyonel alanlar genellikle güvenlidir.
  • Yeni endpoint’ler genellikle güvenlidir.
  • Mevcut request/response şekillerini değiştirmek risklidir.

• Adlandırma tutarlı mı?

  • Endpoint path’leri API’nin geri kalanıyla uyumlu mu?
  • Çoğul/tekil kullanım aynı mı?
  • Field casing standardı korunuyor mu?

• Operasyon eksiksiz mi?

  • summary var mı?
  • Başarılı response şeması var mı?
  • Hata response’ları tanımlı mı?
  • Request body gerekiyorsa şeması açık mı?

• Örnekler gerçekçi mi?

  • Belgeler ve mock veriler için kullanılabilir örnekler var mı?

Bozan değişiklik tespiti için yalnızca manuel incelemeye güvenmeyin. CI’da belirtim fark aracı çalıştırın ve PR’daki belirtimi main ile karşılaştırın.

Apidog’dan Commit ve Push Yapma

Ham YAML düzenlemek mümkündür, ancak görsel düzenleyici ve canlı doğrulama hataları daha erken yakalamanıza yardımcı olur.

Apidog’un Spec-First Modu, OpenAPI belirtimi için iki yönlü Git senkronizasyonu sağlar:

1. Git deponuzu Apidog’a bağlayın.
2. Apidog’u ilgili OpenAPI dosyasına yönlendirin.
3. Endpoint, schema ve örnekleri görsel düzenleyicide güncelleyin.
4. Apidog değişiklikleri YAML dosyasına yazar.
5. Dal üzerinden commit ve push yapın.
6. Normal Git akışınızla PR açın.

Bu akışta amaç, belirtim değişikliklerini Git dışına taşımak değil; tam tersine Git geçmişi, PR incelemesi ve CI kontrollerini koruyarak daha hızlı düzenleme yapmaktır.

Kurulum detayları için Apidog Spec-First Modu belgelerine bakabilirsiniz. Belirtimi GitHub ile senkronize etmek istiyorsanız OpenAPI belirtiminizi GitHub ile senkronize etmeye göz atın.

CI Doğrulama Kancaları

Geçersiz bir belirtimin main dalına merge edilmesine izin vermeyin. OpenAPI doğrulamasını PR kontrollerine ekleyin.

Minimum GitHub Actions örneği:

name: Validate OpenAPI

on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint spec
        run: npx @redocly/cli lint api/openapi.yaml

Bu adım şunları yakalamanıza yardımcı olur:

• Geçersiz YAML
• Eksik veya hatalı OpenAPI alanları
• Stil ve yapı sorunları
• Yanlış $ref kullanımları

Daha gelişmiş bir akışta ek kontroller kullanın:

name: Validate OpenAPI

on: [pull_request]

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

      - name: Lint OpenAPI spec
        run: npx @redocly/cli lint api/openapi.yaml

      - name: Validate OpenAPI parse
        run: npx @redocly/cli bundle api/openapi.yaml --output /tmp/openapi.yaml

Bozan değişiklik tespiti için PR’daki belirtimi main ile karşılaştıran ayrı bir adım ekleyin. Örneğin oasdiff gibi araçlar kaldırılan alanları, yeni required parametreleri ve tip değişikliklerini işaretleyebilir.

En İyi Uygulamalar

OpenAPI sürüm kontrolünü sürdürülebilir tutmak için şu kuralları uygulayın:

• Semantik sürümleme kullanın.
  
  info.version alanını değişiklik türüne göre artırın. Bozan değişiklik yeni ana sürüm gerektirir.

• CHANGELOG tutun.
  
  Belirtimin yanında kısa bir CHANGELOG.md, API tüketicilerine sürümler arasında ne değiştiğini gösterir.

• Küçük PR’lar açın.
  
  Her PR tek mantıksal değişiklik içermeli. Büyük belirtim PR’ları bozan değişiklikleri gizler.

• Açıklayıcı commit mesajları yazın.
  
  İyi:
  

  add refundReason to refund request

Zayıf:

  update spec

• main üzerinde doğrudan düzenleme yapmayın.
  
  Küçük bir yazım hatası için bile dal açın, commit edin ve PR ile merge edin.

• Diff dostu formatı koruyun.
  
  Otomatik formatlama kullanıyorsanız ekip genelinde aynı formatter veya araç ayarlarını kullanın.

Sıkça Sorulan Sorular

Bir OpenAPI belirtimindeki bozan değişiklikleri nasıl tespit ederim?

CI’da PR’daki belirtimi main üzerindeki sürümle karşılaştıran bir belirtim fark aracı çalıştırın. oasdiff gibi araçlar değişiklikleri bozan, bozan olmayan veya sınıflandırılmamış olarak ayırabilir. Bozan değişiklik bulunduğunda build’i başarısız yaparak kaldırılan alanları, yeni required parametreleri ve değişen tipleri otomatik yakalayabilirsiniz.

Tek bir OpenAPI dosyası mı tutmalıyım, yoksa birçok dosyaya mı bölmeliyim?

Tek bir openapi.yaml ile başlayın. İncelemesi, lint edilmesi ve sürümlenmesi daha kolaydır.

Dosya büyüdüğünde veya birden çok ana sürümü paralel sürdürdüğünüzde şu seçenekleri kullanabilirsiniz:

• Ana sürüme göre ayırma: api-v1.yaml, api-v2.yaml
• Ortak şemaları $ref ile ayrı dosyalara taşıma
• Servis bazlı belirtim dosyaları kullanma

Erken bölmeyin. Tek ve okunabilir bir dosya, beş parçalı ve takip edilmesi zor bir yapıdan daha iyidir.

Belirtimimi elle YAML yazmadan sürüm kontrolüne alabilir miyim?

Evet. Apidog’un Spec-First Modu, belirtimi görsel düzenleyicide düzenlemenize ve değişiklikleri Git ile çift yönlü senkronize etmenize olanak tanır. Böylece YAML’ı elle yazmadan da Git geçmişi, PR incelemesi ve CI doğrulamasını koruyabilirsiniz.