Git Tabanlı API Test ve Geliştirme İşbirliği

OpenAPI spesifikasyonunuz, API'niz ile tüketicileri arasındaki sözleşmedir. Peki bu sözleşme nerede duruyor?

Çoğu zaman, API spesifikasyonları izole araçlarda kalır; bir kez dışa aktarılır, unutulur ve uygulama değiştiğinde nadiren güncellenir. Dokümantasyon sapar. Test koleksiyonları ayrışır. İnceleyenler, ilgili spesifikasyon güncellemelerini görmeden kod değişikliklerini onaylar.

Spec-first Modu bu modeli değiştirir. OpenAPI veya Swagger dosyalarınız, uygulama koduyla birlikte doğrudan Git deponuzda depolanarak doğruluk kaynağı haline gelir. Her spesifikasyon değişikliği, zaten kullandığınız aynı dallardan, çekme isteklerinden ve inceleme sürecinden geçer. API tasarımı, test ve dokümantasyon, otomatik olarak senkronize kalır.

Bu eğitimde, size Apidog'da bir Spec-first projesi kurmayı, ekibinizle spesifikasyonları düzenlemeyi ve her şeyi Git iş akışınızla senkronize tutmayı göstereceğim.

Spec-first Modu Nedir?

Tipik bir API projesinde, görsel formlar aracılığıyla uç noktalar oluşturur veya mevcut spesifikasyonları başlangıç noktası olarak içe aktarırsınız. Araç, API tanımlarını dahili olarak depolar ve Git entegrasyonu (varsa) bir dışa aktarma adımıdır.

Spec-first Modu farklıdır. Birincil çalışma alanı dosya tabanlıdır:

• openapi.yaml veya openapi.json deponuzda bulunur
• Apidog bu dosyaları ayrıştırır ve gezinilebilir bir API yapısı oluşturur
• Dosyaları doğrudan (veya desteklenen formlar aracılığıyla) düzenlersiniz
• Değişiklikler otomatik olarak Git'e geri senkronize olur

Spesifikasyon dosyası her zaman yetkilidir. Apidog onu okur, ona yazar ve deponuzla senkronize tutar.

Önkoşullar

Devam etmek için şunlara ihtiyacınız olacak:

• Bir Apidog hesabı (ücretsiz katman yeterlidir)
• Bir OpenAPI/Swagger dosyası içeren bir Git deposu veya sıfırdan başlamak için boş bir depo
• Depoya yazma erişimi
• OpenAPI veya Swagger sözdizimine temel aşinalık

Adım 1: Spec-first Projesi Oluşturun

Apidog'da + Yeni Proje'ye tıklayın ve proje türü olarak Spec-first Modu'nu seçin.

Ardından, Git sağlayıcınızı bağlayın:

1. Sağlayıcınızı seçin (GitHub, GitLab, Azure DevOps veya Bitbucket)
2. Bir organizasyon veya çalışma alanı seçin
3. Mevcut bir depoyu seçin veya yeni bir tane oluşturun
4. Senkronizasyon için ana dalı seçin

Apidog, deponuzun varsayılan dalıyla senkronize olur. Eğer adı main değilse, Apidog otomatik olarak uyum sağlar.

Adım 2: Webhook Senkronizasyonunu Yapılandırın (Önerilen)

Kurulum sırasında, bir webhook yükleme seçeneği göreceksiniz. Bu, ekibiniz depoya her push yaptığında otomatik senkronizasyonu etkinleştirir.

Not: Webhook kurulumu genellikle depoda yönetici izni gerektirir. Yönetici erişiminiz yoksa, bu adımı atlayın—yine de Git Pull kullanarak manuel olarak senkronize edebilirsiniz.

Webhook faydaları:

• Ekip değişiklikleri push eder → Apidog otomatik olarak senkronize olur
• Manuel yenilemeye gerek kalmaz
• Herkes en son spesifikasyon durumunu görür

Webhook kurulumunu başlangıçta atladıysanız, daha sonra Proje Ayarları > Git & Dallar'dan ekleyebilirsiniz.

Adım 3: Spesifikasyonlar Çalışma Alanını Keşfedin

Oluşturulduktan sonra, projeniz Spesifikasyonlar çalışma alanını açar—dosya tabanlı düzenleme ve Git işlemleri için merkezi merkez.

Üç panel birlikte çalışır:

Yapı ağacındaki bir uç noktaya tıklayın → Apidog, kaynak dosyanızdaki ilgili bölümü vurgular. Sekmeleri değiştirmeden üst düzey API görünümünden alt düzey YAML'ye geçiş yapın.

Adım 4: Spesifikasyon Dosyalarınızı Düzenleyin

Kod Görünümü: Doğrudan Düzenleme

Çoğu dosya için—YAML, JSON, Markdown—ham metni düzenlemek için Kod görünümünü kullanın.

Düzenlemeleriniz dosyada kalır. Apidog bunları dönüştürmez veya ayrı olarak depolamaz. Spesifikasyon dosyası tek doğruluk kaynağı olmaya devam eder.

Form Görünümü: Yapılandırılmış Düzenleme

Desteklenen OpenAPI düğümleri—uç noktalar, şemalar, tanımlar ve API genel bakışı—için Form görünümüne geçin.

Form görünümü şu durumlarda kullanışlıdır:

• YAML yapısını ezberlemeden tüm gerekli alanlarla uç noktalar eklemek
• Şemaları görsel olarak düzenlemek
• Güvenlik tanımlarını ve API meta verilerini güncellemek

Bir düğüm form düzenlemeyi desteklemiyorsa, Apidog sizi kod görünümünde tutar.

Adım 5: Anında Doğrulayın ve Önizleyin

Spec-first Modu, gerçek zamanlı doğrulama ve dokümantasyon önizlemesi içerir—harici araçlara gerek yoktur.

Doğrulama ile Sorunları Kontrol Edin

Düzenleyici başlığındaki Doğrulama'ya tıklayın. Bir panel, mevcut spesifikasyonunuzdaki tüm uyarıları ve hataları gösterir.

Rozet, toplam sorun sayısını gösterir. Yakalananlar:

• Sözdizimi hataları
• Eksik gerekli alanlar
• Şema ihlalleri
• Adlandırma kuralı sorunları

Taahhüt etmeden önce sorunları düzeltin. Ekibinizin inceleyenleri bunları manuel olarak tespit etmek zorunda kalmayacak.

Dokümantasyonunuzu Önizleyin

Spesifikasyonunuzun API dokümantasyonu olarak nasıl render edildiğini görmek için Önizle'ye tıklayın.

Uç noktalar için önizleme iki sekme içerir:

Şemalar ve tanımlar için önizleme, render edilmiş dokümantasyon görünümünü gösterir.

Doğrulama ve Önizleme aynı yan paneli paylaşır. Birini açmak diğerini otomatik olarak kapatır.

Adım 6: Ekibinizden Güncellemeleri Çekin

İşbirlikçiler deponuza değişiklikler push ettiklerinde, bunları Apidog'a getirin:

1. Spesifikasyonlar çalışma alanını açın
2. Yan çubuktaki mevcut dal adına tıklayın
3. Git Pull'u seçin

Webhook senkronizasyonu etkinse, Apidog depo push olaylarında otomatik olarak çeker—manuel adıma gerek kalmaz.

Adım 7: Değişikliklerinizi Taahhüt Edin ve Push Edin

Apidog'da dosyaları düzenledikten sonra, güncellemelerinizi Git'e geri gönderin:

1. Spesifikasyonlar çalışma alanında değişiklikler yapın
2. Değiştirilen, eklenen, yeniden adlandırılan ve silinen dosyaları görmek için yan çubuktaki Değişiklikler'e tıklayın
3. Taahhüt Et ve Push Et'e tıklayın
4. Dahil edilecek dosyaları seçin
5. Bir taahhüt mesajı yazın
6. Push Et'e tıklayın

Spesifikasyon güncellemeleriniz artık kod değişikliklerinizle aynı çekme isteği iş akışında görünür. Ekip arkadaşlarınız hem uygulamayı hem de API sözleşmesini tek bir yerde inceleyebilir, yorum yapabilir ve onaylayabilir.

İpucu: Push etmeden önce yerel düzenlemeleri iptal etmek isterseniz Tüm değişiklikleri iptal et'i kullanın.

Adım 8: Dallar ile Çalışın

Spec-first Modu, tam dal tabanlı işbirliğini destekler. Apidog, Git dallarını proje dallarıyla eşleştirerek spesifikasyon sürümleri arasında geçiş yapmanızı sağlar.

Yaygın Dal İşlemleri

Dal yönetimi, Git'ten beklediğiniz gibi çalışır—özellik dalları, sürümler ve paralel geliştirme hepsi doğru şekilde senkronize olur.

Adım 9: CI/CD ile Entegre Edin

Spesifikasyonlarınız Git'te yaşadığı için, otomasyon pipeline'larına doğal olarak uyum sağlarlar:

• Apidog doğrulaması veya Spectral gibi araçlar kullanarak her PR'da spesifikasyonları lint edin
• Spesifikasyonlar ana dalla birleştiğinde otomatik olarak dokümantasyon oluşturun
• Spesifikasyon değişiklikleri tarafından tetiklenen API testlerini çalıştırın
• Alt sistemlerle senkronize edin—API ağ geçitleri, sahte sunucular, SDK oluşturucular

Örnek GitHub Actions iş akışı:

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

API spesifikasyonlarınız artık uygulama kodunuzla aynı kalite kapılarından geçer.

Alternatif: Depolama Destekli Projeler

Harici bir Git deposunu bağlamaya hazır değilseniz, Apidog depolama destekli Spec-first projeleri sunar.

Bu projeler Apidog'un dahili depolamasını kullanır ancak yine de şunları sağlar:

• Dosya tabanlı düzenleme
• Doğrulama ve önizleme
• Dal yönetimi

Kullanıcı arayüzü etiketleri biraz ayarlanır:

• Git Pull, Senkronize Et olur
• Taahhüt Et ve Push Et, Kaydet olur

Ekibiniz hazır olduğunda harici Git'e geçin.

Özet

Spec-first Modu ile API iş akışınız şöyle olur:

Spec-first Modu, OpenAPI dosyalarını olması gereken sözleşme haline getirir—sürümü belirlenmiş, incelenmiş ve her zaman kodunuzla uyumlu.

Denemeye hazır mısınız? Apidog'da bir Spec-first projesi oluşturun ve ilk deponuzu bağlayın.