Kodunuz Git'te yaşıyor. CI işlem hatlarınız, incelemeleriniz ve sürüm geçmişiniz Git'te yaşıyor. Peki API spesifikasyonunuz neden başka bir yerde yaşıyor?
Git tabanlı bir API iş akışı, OpenAPI tanımınızı kodunuzla aynı yerde tutar. Spesifikasyonu düz bir YAML veya JSON dosyası olarak düzenler, taahhüt eder ve diğer her şey için kullandığınız aynı inceleme sürecinden geçirirsiniz. Ayrı bir bulut veritabanı yok. Dışa aktarma-içe aktarma karmaşası yok. Spesifikasyon, deponuzdaki diğer bir dosyadan ibarettir.
Git tabanlı bir API iş akışı ne anlama geliyor?
Git tabanlı bir API iş akışı, API spesifikasyonunuzu kod olarak ele alır. OpenAPI dosyası, hizmetlerinizin yanında bir depoda bulunur. Her değişiklik bir taahhüttür (commit). Her taahhüdün bir yazarı, bir mesajı ve bir farkı (diff) vardır.
Bu size, kaynak koddan zaten beklediğiniz üç şeyi sağlar:
- Sürüm geçmişi. Bir uç noktayı kimin ve ne zaman değiştirdiğini görebilirsiniz. `git blame` spesifikasyonunuz üzerinde çalışır.
- Dallanma ve inceleme. Spesifikasyon değişiklikleri çekme isteklerinden (pull request) geçer. İnceleyiciler, herhangi bir şey birleşmeden önce tam farkı görür.
- Tek doğruluk kaynağı. `main` dosyasındaki dosya, sözleşmedir. Araçlar, belgeler ve sahteler (mocks) hepsi ondan okur.
Bu, spesifikasyon odaklı bir API iş akışının temel fikridir: spesifikasyon yol gösterir ve uygulama onu takip eder. Bu pratiğe daha derinlemesine bir bakış için, spesifikasyon odaklı API geliştirme kılavuzumuza bakın.
Karşıt yaklaşım, spesifikasyonunuzu tescilli bir bulut uygulamasının içinde depolar. Bu, ekibiniz büyüyene veya süreciniz olgunlaşana kadar işe yarar. Sonra çatlaklar ortaya çıkar.
Bulut kilitli API spesifikasyonlarının sorunu
Çoğu API tasarım aracı, spesifikasyonu kendi veritabanlarında tutar. Kendi kullanıcı arayüzleri aracılığıyla düzenleme yaparsınız. Sahip olduğunuzu düşündüğünüz "dosya" aslında başkasının sistemindeki bir satırdır.
Bu, öngörülebilir şekillerde bozulur.
İnceleme iki yerde gerçekleşir. Kod değişiklikleri GitHub üzerinden geçer. Spesifikasyon değişiklikleri, kendi yorumları ve geçmişi olan ayrı bir araç üzerinden geçer. İnceleyiciler bağlam değiştirir. Onaylar senkronizasyon dışına çıkar.
Fark gizlenir. Spesifikasyon bir bulut veritabanında yaşadığında, çekme isteğinizde temiz, satır satır bir fark göremezsiniz. Ne değiştiğini bilmeden "tasarımın v3'ünü" onaylarsınız.
Dışa aktarma bir angarya haline gelir. Spesifikasyonu CI'ya almak için dışa aktarır, dışa aktarmayı taahhüt eder ve bu arada kimsenin bulut kopyasını düzenlememiş olmasını umarsınız. İki doğruluk kaynağı, kaçınılmaz bir çakışma.
Otomasyon sizinle savaşır. Linters, sözleşme testleri ve kod üreteçleri diskte bir dosya ister. Bulut kilitli bir spesifikasyon, bunların herhangi biri çalışmadan önce bir alma adımı gerektirir.
API spesifikasyonunuzu kod olarak ele almak, tüm bunları ortadan kaldırır. Dosya spesifikasyondur. Git, geçmişdir. Mevcut işlem hattınız gerisini halleder. Bu prensibi API spesifikasyonunu kod olarak ele alma kılavuzumuzda ayrıntılı olarak ele alıyoruz.
Apidog Spec-First Modu nasıl çalışır?
Spec-First Modu, zaten taahhütler ve dallar (branches) hakkında düşünen ekipler için tasarlanmıştır. API'yi ham YAML veya JSON dosyaları olarak tasarlarsınız ve Apidog bu dosyaları Git deponuzla iki yönlü senkronize tutar.
İşte ne elde edersiniz.
IDE tarzı bir OpenAPI düzenleyici
Spesifikasyonu bir formda değil, bir kod düzenleyicide yazarsınız. Düzenleyici, bir IDE'den bekleyeceğiniz kolaylıkları sunar:
- YAML ve JSON için sözdizimi vurgulama.
- OpenAPI ve Swagger şemalarına karşı doğrulama, böylece yazdıkça hatalar yüzeye çıkar.
- OpenAPI anahtar kelimeleri, türleri ve referansları için otomatik tamamlama.
Tam dosyanın kontrolünü sizde tutarsınız. Gizli alanlar yok, sadece UI'ya özgü meta veriler yok.
Ham YAML/JSON dosyaları
Spesifikasyon gerçek bir dosyadır. İşte küçük bir parçası:
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, deponuza inen dosyadır. Düzenlediğiniz şey, taahhüt edilen şeydir.
Otomatik ayrıştırılan gezilebilir bir taslak
Siz yazarken, Apidog dosyayı ayrıştırır ve sol kenar çubuğunda görsel bir taslak oluşturur. Yollar, işlemler ve şemalar tıklayabileceğiniz bir ağaç olarak görünür. Hem bir tasarım aracının okunabilirliğini hem de ham dosyaların hassasiyetini aynı anda elde edersiniz.
Uzun spesifikasyonlar gezilebilir kalır. Yüzlerce satır arasında kaydırmadan bir uç noktaya atlayın.
İki yönlü Git senkronizasyonu
Spec-First Modu, Git sağlayıcınıza bağlanır ve değişiklikleri her iki yönde senkronize eder. GitHub ve GitLab'i doğrudan, Azure DevOps'u ise bir Git Bağlantısı aracılığıyla destekler.
Ekip arkadaşlarınızın gönderdiği değişiklikleri içeri çekin. Apidog düzenleyicisinde yerel olarak düzenleyin. Ardından aynı dalla taahhüt edin ve geri gönderin. Depo ve çalışma alanınız uyumlu kalır.
Taahhüt, gönderme ve senkronizasyon durumu göstergesi
Git'i yönetmek için Apidog'dan ayrılmazsınız. Değişikliklerinizi hazırlayın, bir taahhüt mesajı yazın ve gönderin. Bir senkronizasyon durumu göstergesi, nerede durduğunuzu size bildirir. Başarılı bir göndermeden sonra, "Az önce senkronize edildi" gibi bir şey yazar. Göndermeden önce fikrinizi değiştirirseniz, gönderilmemiş düzenlemeleri iptal edebilir ve son senkronize edilmiş duruma geri dönebilirsiniz.
Bu iki yönlü senkronizasyon, Git tabanlı API iş akışının kalbidir. GitHub tarafının odaklanmış bir kılavuzu için, OpenAPI spesifikasyonunu GitHub ile senkronize etme bölümüne bakın.
Kurulum kılavuzu
Boş bir depodan senkronize edilmiş bir spesifikasyona nasıl geçileceği aşağıda açıklanmıştır. Tam referans, Spec-First Modu belgelerinde yer almaktadır.
- Bir depodan proje oluşturun. Apidog'da yeni bir Spec-First projesi başlatın ve Git sağlayıcınızı bağlayın. API spesifikasyonunuzu içeren depoyu seçin ve genellikle `main` olan izlenecek dalı seçin. Apidog, mevcut spesifikasyon dosyalarını düzenleyiciye çeker.
- Spesifikasyonu düzenleyin. OpenAPI dosyasını düzenleyicide açın. Bir uç nokta ekleyin, bir şemayı ayarlayın veya bir yanıtı düzeltin. Sözdizimi vurgulama, doğrulama ve otomatik tamamlama yazarken size rehberlik eder. Dosya değiştikçe sol kenar çubuğu taslağı güncellenir.
- Değiştirilen, eklenen ve silinen dosyaları izleyin. Apidog, son senkronizasyondan bu yana hangi dosyaları değiştirdiğinizi gösterir. Değiştirilen, eklenen ve silinen dosyalar işaretlenir, böylece taahhüde neyin gireceğini tam olarak bilirsiniz.
- Bir taahhüt mesajı yazın. Değişikliği, herhangi bir Git istemcisinde yaptığınız gibi, anlaşılır bir dilde açıklayın. "getOrder'a 404 yanıtı ekle" ifadesi, "spesifikasyonu güncelle" ifadesinden daha iyidir.
- Gönderin (Push). Taahhüdü izlenen dala gönderin. Ekip arkadaşlarınız ve CI işlem hattınız artık yeni sürümü görür.
- "Az önce senkronize edildi" ifadesini kontrol edin. Senkronizasyon durumu göstergesinin göndermeyi onayladığını izleyin. "Az önce senkronize edildi" yazdığında, yerel düzenlemeleriniz ve uzak dal eşleşir. Buradan, değişiklik normal çekme isteği ve inceleme sürecinizden geçer.
Bu tam döngüdür: çekme, düzenleme, taahhüt etme, gönderme, doğrulama. Dışa aktarma adımı yok. İkinci bir doğruluk kaynağı yok.
Spec-first (Spesifikasyon Odaklı) ve Design-first (Tasarım Odaklı) modu
Apidog, iki farklı çalışma şeklini destekler. Fark, spesifikasyonun nerede yaşadığı ve onu nasıl düzenlediğinizdedir.
| 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ü | Yerel Git (taahhütler, dallar, farklar) | Apidog geçmişi ve dalları |
| İki yönlü Git senkronizasyonu | Evet (GitHub, GitLab, Azure DevOps) | Dışa aktarma/içe aktarma yoluyla |
| En uygun olduğu durum | Git'te yaşayan ekipler | Görsel bir iş akışını tercih eden ekipler |
Hiçbir mod "daha iyi" değildir. Farklı alışkanlıklara hizmet ederler. İnceleme ve yayınlama süreciniz zaten Git üzerinde çalışıyorsa, Spec-First Modu bu boşluğu ortadan kaldırır. Ekibiniz görsel olarak tasarım yapıyor ve ham OpenAPI'ye nadiren dokunuyorsa, Design-First Modu daha uygun olabilir.
Ne zaman kullanılır?
Spec-First Modu'nu şu durumlarda kullanın:
- Spesifikasyonunuz çekme isteklerinden (pull request) ve kod incelemesinden geçmelidir.
- API sözleşmenizde `git blame` ve gerçek bir taahhüt geçmişi istiyorsunuz.
- CI'nız, diskte bir dosyaya ihtiyaç duyan spesifikasyon denetimi, sözleşme testleri veya kod oluşturma çalıştırıyor.
- Birden fazla mühendis spesifikasyonu düzenliyor ve temiz, birleştirilebilir farklar (diff) istiyorsunuz.
- Bir araçtan dışa aktarıp diğerine beslemekten yoruldunuz.
Ekibiniz ham OpenAPI yazmadan API tasarladığında veya mühendis olmayanlar spesifikasyonu sahiplendiğinde ve form tabanlı bir düzenleyiciyi tercih ettiğinde görsel, bulut öncelikli bir yaklaşıma sadık kalın.
SSS
Git tabanlı bir API iş akışı nedir?
Git tabanlı bir API iş akışı, OpenAPI spesifikasyonunuzu bir Git deposunda bir dosya olarak depolar ve her değişikliği taahhütler, dallar ve çekme istekleri aracılığıyla yönetir. Spesifikasyon, uygulama kodunuzla aynı inceleme ve sürüm kontrolü sürecini takip eder, böylece tek bir doğruluk kaynağı olur.
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, bir Git Bağlantısı aracılığıyla desteklenir. Depoyu bağlarsınız, bir dal seçersiniz ve Apidog düzenlemelerinizi ve uzaktaki depoyu senkronize tutar.
OpenAPI dosyalarını ham YAML veya JSON olarak düzenleyebilir miyim?
Evet. Spec-First Modu, ham YAML ve JSON için sözdizimi vurgulama, şema doğrulama ve OpenAPI ve Swagger için otomatik tamamlama özelliklerine sahip IDE tarzı bir düzenleyici sunar. Sol kenar çubuğundaki bir taslak, büyük spesifikasyonlarda hızlıca gezinmenizi sağlamak için dosyayı otomatik olarak ayrıştırır.
Spec-First ve Design-First modları arasındaki fark nedir?
Spec-First Modu, spesifikasyonunuzu Git'te dosya olarak tutar ve bunları iki yönlü senkronizasyonlu bir kod düzenleyicide düzenler. Design-First Modu, spesifikasyonu görsel, form tabanlı bir düzenleyiciyle Apidog bulut projesinde tutar. İş akışınız zaten Git üzerinde çalışıyorsa Spec-First'ı seçin.
Sonuç
Git tabanlı bir API iş akışı, kodunuzla API sözleşmeniz arasındaki ayrımı sona erdirir. Spesifikasyon bir dosya haline gelir, dosya bir taahhüt haline gelir ve taahhüt, zaten güvendiğiniz inceleme sürecinden akar.
Apidog Spec-First Modu, bunu gerçeğe dönüştürmek için size IDE tarzı düzenleyiciyi, gezilebilir taslağı ve iki yönlü Git senkronizasyonunu sunar. Ham YAML veya JSON'u düzenlersiniz, net bir mesajla taahhüt eder, gönderir ve durumun "Az önce senkronize edildi" olarak görünmesini izlersiniz.
Spec-First Modu'nu deneyin ve API spesifikasyonunuzu Git'e taşıyın.