Apidog Spec-First Modu Nedir?

Apidog Spec-First Modu, OpenAPI spesifikasyonlarını kaynak kodu olarak ele alan ekipler için oluşturulmuş bir beta çalışma alanıdır. Spesifikasyonu doğrudan bir IDE tarzı düzenleyicide YAML veya JSON olarak yazarsınız, ardından bağlı bir Git deposuyla çift yönlü olarak senkronize edersiniz. Sizinle dosya arasında form tabanlı bir düzenleyici bulunmaz. Spesifikasyon projenin *kendisidir*. Eğer `openapi.yaml` dosyasını gerçek bir kod düzenleyicide düzenleyip API aracınızdan ayrılmadan GitHub'a göndermek istediyseniz, bu mod tam size göre.

Bu kılavuz, özelliğin kendisi için eksiksiz bir referanstır. Her yeteneği, eksiksiz kurulum kılavuzunu, kimler için olduğunu, bir beta sürümünden beklenen sınırlamaları ve pratik bir SSS'yi kapsar. Bu yaklaşımın arkasındaki daha geniş fikir için Git-yerel API iş akışı yazımıza göz atın.

Apidog Spec-First Modu Nedir?

Spec-First Modu, API tasarımınızın ham bir OpenAPI belgesi olarak bulunduğu Apidog'daki bir beta düzenleme modudur. Dosyayı açar, YAML veya JSON'u düzenler, doğrular, kaydeder (commit) ve Git'e gönderirsiniz (push). Apidog, spesifikasyonu ve depoyu her iki yönde de senkronize tutar. Bir ekip arkadaşınızın değişikliğini çektiğinizde (pull), düzenleyiciniz güncellenir. Düzenlemenizi gönderdiğinizde (push), depo güncellenir.

Özellikle tek tip bir ekip için tasarlanmıştır: zaten yerel bir Git iş akışı kullanan kişiler. Backend mühendisleri, platform ekipleri ve sözleşmelerini çekme isteklerinde (pull requests) sürümleyen API-first şirketler kendilerini evlerinde hissedeceklerdir. Spesifikasyon dosyası tek doğruluk kaynağı haline gelir ve Git, kod tabanınızın geri kalanı için yaptığı gibi geçmişi, incelemeyi ve dallanmayı yönetir.

Bu, çoğu API aracının çalışma şeklinden farklıdır. Çoğu araç spesifikasyonu grafiksel bir formun arkasına gizler. Spec-First Modu size dosyayı gösterir.

Spec-First Modu ve Design-First Modu: Bir Bakışta Farklar

Apidog iki mod sunar. Design-First Modu, çoğu ekibin başladığı görsel, form tabanlı düzenleyicidir. Spec-First Modu, bu kılavuzun kapsadığı kod düzenleyici yaklaşımıdır. İşte kısa versiyonu. Avantaj ve dezavantajların tam dökümü için spec-first vs design-first karşılaştırması yazımızı okuyun.

Hiçbir mod "daha iyi" değildir. Farklı ekiplere hizmet ederler. Aralarında geçiş yapabilirsiniz, bunu aşağıda ele alacağız.

Temel Özellikler

Spec-First Modu bir metin kutusundan daha fazlasıdır. Bir düzenleyici, bir gezgin, Git entegrasyonu ve ekip kontrollerini bir araya getirir. İşte her bir yetenek ayrıntılı olarak.

IDE Tarzı OpenAPI Düzenleyici

Çalışma alanının merkezi, OpenAPI belgeniz için tam teşekküllü bir kod düzenleyicidir. Ham YAML veya JSON'u doğrudan düzenlersiniz. Her gün kullandığınız düzenleyici gibi davranır.

Anahtarları, değerleri ve yapıyı renklendiren sözdizimi vurgulaması sayesinde dosya büyük ölçekte okunabilir kalır. Yazarken OpenAPI spesifikasyonuna karşı hataları işaretleyen şema doğrulaması alırsınız, böylece hatalı biçimlendirilmiş bir yanıt nesnesi veya eksik bir zorunlu alan anında görünür. Yazarken geçerli anahtar kelimeler, alan adları ve yapılar öneren OpenAPI ve Swagger için ayarlanmış otomatik tamamlama özelliği alırsınız.

Bu otomatik tamamlama, bir şemanın derinliklerindeyken `additionalProperties` mi yoksa `additionalItems` mı olduğunu hatırlayamadığınızda en çok önem kazanır. Düzenleyici spesifikasyonu bildiği için doğru kalmanıza yardımcı olur.

düzenleyeceğiniz küçük bir kesit:

paths:
 /users/{userId}:
 get:
 summary: Get a user by ID
 operationId: getUserById
 parameters:
 - name: userId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: A single user
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/User'

Otomatik Ayrıştırılmış Gezinilebilir Taslak

Ham bir spesifikasyon dosyası hızla uzar. Gerçek bir API binlerce satır uzunluğunda olabilir. Spec-First Modu bunu, dosyayı görsel bir taslağa otomatik olarak ayrıştıran sol bir kenar çubuğuyla çözer.

Siz yazdıkça, Apidog belgeyi okur ve gezilebilir bir yapı oluşturur: yollar (paths), operasyonlar (operations), şemalar (schemas) ve bileşenler (components). Taslaktaki herhangi bir düğmeye tıkladığınızda, düzenleyici dosyadaki o noktaya atlar. Anlama göre gezinirsiniz, kaydırarak değil. Taslak, spesifikasyon değiştikçe canlı olarak güncellenir, böylece her zaman dosyada gerçekten ne olduğunu yansıtır.

Bu, büyük bir `openapi.yaml` dosyasını yönetilebilir kılar. “`POST /orders` operasyonu” terimleriyle düşünürsünüz, “1.847. satır” olarak değil.

Çift Yönlü Git Senkronizasyonu

Bu, modun çekirdeğidir. Spec-First Modu, Git deponuza bağlanır ve spesifikasyonu her iki yönde de senkronize eder.

GitHub ve GitLab doğrudan desteklenir. Azure DevOps, Apidog'u standart Git kimlik bilgileri kullanarak depoya yönlendirmenizi sağlayan genel bir Git Bağlantısı aracılığıyla çalışır. Bağlandıktan sonra, çekme (pull) işlemi depo değişikliklerini düzenleyicinize getirir ve gönderme (push) işlemi düzenlemelerinizi depoya geri gönderir. Git ortak omurga olduğu için spesifikasyon ekipteki herkes için tutarlı kalır.

Belirli bir sağlayıcıya odaklanmış, adım adım bir kılavuz isterseniz, OpenAPI spesifikasyonunu GitHub'a senkronize etme kılavuzumuz tam olarak bu akışı anlatır.

Kaydet, Gönder ve Senkronizasyon Durum Göstergesi

Sadece kaydedip umut etmekle kalmazsınız. Spec-First Modu, zaten bildiğiniz Git modelini izler. Bir düzenlemeyi bitirdiğinizde, bir commit mesajı yazar ve değişikliği kaydedersiniz (commit). Ardından bağlı depoya gönderirsiniz (push).

Bir senkronizasyon durum göstergesi sizi her zaman bilgilendirir. Yerel spesifikasyonunuz depoyla eşleştiğinde "Şimdi senkronize edildi" gibi durumları gösterir ve gönderilmemiş (unpushed) işiniz olduğunda değişir. Önünüzdeki sürümün ekip arkadaşlarınızın gördüğü sürüm olup olmadığını her zaman bilirsiniz. Tahmin yok, eski spesifikasyon yok.

Dosya Değişikliği Takibi

Kaydetmeden (commit) önce, Spec-First Modu size tam olarak neyin değiştiğini gösterir. Değişiklikleri dosya düzeyinde izler ve her girişi değiştirilmiş, eklenmiş veya silinmiş olarak işaretler. Değişiklik setini, bir Git durum çıktısını incelediğiniz gibi incelersiniz.

Bu önemlidir çünkü size bir kontrol noktası sağlar. Doğru düzenlemeleri kaydettiğinizden ve fazladan bir şey olmadığından emin olabilirsiniz. Ve bir deneyin işe yaramadığına karar verirseniz, gönderilmemiş (unpushed) düzenlemeleri depoya ulaşmadan önce atabilirsiniz. Bu, paylaşılan geçmişinizi temiz tutar. Yerel keşif, siz göndermeyi seçene kadar yerel kalır.

Şube ve Depo Kapsamlı, Ekip İzinleriyle Projeler

Bir Spec-First projesi soyut bir şekilde dolaşmaz. Onu belirli bir depodan ve genellikle `main` olan belirli bir daldan oluşturursunuz. Bu kapsamlandırma, projenin her zaman Git'teki gerçek bir noktayı işaret ettiği anlamına gelir. Spesifikasyonunuz, geçmişiniz ve dalınız hizalanır.

Ekip izinleri kurulum sırasında yapılandırılır. Projeye kimlerin erişebileceğine ve ne yapabileceğine siz karar verirsiniz, böylece sözleşme üzerinde çalışan kişiler istediğiniz kişiler olur. Proje bir depoya ve dala bağlı olduğu için, erişim modeliniz Git'te zaten uyguladığınız erişim modelini yansıtabilir.

Spec-First Modu Nasıl Kurulur

Kurulum kısa, doğrusal bir akıştır. Bu adımları izleyin. Ekran görüntüleriyle birlikte bir kılavuz isterseniz, resmi kılavuz docs.apidog.com/spec-first-mode-beta-2058268m0 adresinde bulunmaktadır.

1. Modu değiştirin. Apidog'da API'ler modülünü açın. Modülün sol altındaki mod düğmesini bulun ve Design-First'ten Spec-First Modu'na geçin.
2. Git sağlayıcınızı bağlayın. GitHub veya GitLab'ı doğrudan yetkilendirin. Azure DevOps için, Git kimlik bilgilerinizle genel bir Git Bağlantısı kurun.
3. Deponuzdan bir proje oluşturun. Spesifikasyonunuzu içeren depoyu seçin ve genellikle `main` olan dalı seçin. Apidog yeni projeyi bu depoya ve dala kapsar.
4. Ekip izinlerini yapılandırın. Kurulum sırasında projeye kimlerin erişebileceğini ve ne değiştirebileceklerini belirleyin.
5. Spesifikasyonu düzenleyin. `openapi.yaml` veya `openapi.json` dosyanızı IDE tarzı düzenleyicide açın. Gezinmek için soldaki taslağı kullanın. Yazarken doğrulamaya ve otomatik tamamlamaya güvenin.
6. Değişikliklerinizi kaydedin (commit). Açık bir commit mesajı yazın. Önce takip edilen değişiklikleri gözden geçirin. Saklamak istemediğiniz her şeyi atın.
7. Depoya gönderin (push). Kaydettiğiniz (commit) değişikliği bağlı dala gönderin (push).
8. Senkronizasyonu doğrulayın. Senkronizasyon durum göstergesini kontrol edin. "Şimdi senkronize edildi" yazdığında, spesifikasyonunuz ve deponuz eşleşmiş demektir.

Döngünün tamamı budur: geçiş yap, bağlan, oluştur, düzenle, kaydet, gönder, doğrula.

Tipik Bir Günlük İş Akışı

Mod kurulduktan sonra pratikte nasıl hissettirdiği aşağıdadır.

Güne, bağlı daldan en son değişiklikleri çekerek (pull) başlarsınız, böylece düzenleyiciniz ekip arkadaşlarınızın bir önceki gece birleştirdiklerini yansıtır. Taslağı açar, üzerinde çalıştığınız operasyona tıklarsınız ve YAML'ı düzenlemeye başlarsınız. Yeni bir uç nokta bir istek gövdesi gerektirir, bu yüzden bir şema tanımlarsınız. Otomatik tamamlama, alan adlarını doğru yapmanıza yardımcı olur ve doğrulama, bir `$ref` içindeki yazım hatasını sorun haline gelmeden önce yakalar.

Uç nokta iyi göründüğünde, dosya değişikliği takibini kontrol edersiniz. Değişikliklerinizi gösterir. `Add POST /invoices endpoint` gibi bir commit mesajı yazarsınız, kaydedersiniz (commit) ve gönderirsiniz (push). Durum göstergesi "Şimdi senkronize edildi" olarak değişir. Bir ekip arkadaşınız değişikliği normal bir çekme isteğinde (pull request) inceler, çünkü spesifikasyon diğer her şey gibi Git'te yaşar.

Bu akışta yapacağınız türden bir ekleme aşağıdadır:

components:
 schemas:
 Invoice:
 type: object
 required: [id, amount, currency]
 properties:
 id:
 type: string
 format: uuid
 amount:
 type: integer
 description: Amount in the smallest currency unit
 currency:
 type: string
 example: USD
 status:
 type: string
 enum: [draft, sent, paid]

Tüm döngü güvendiğiniz araçların içinde kalır. Spesifikasyon koddur ve ona kod gibi davranırsınız.

Spec-First Modunu Kimler Kullanmalı

Spec-First Modu, bazı ekiplere diğerlerinden daha iyi uyar. Hangi ekip olduğunuz konusunda dürüst olun.

Ekibiniz zaten Git'te yaşıyorsa Spec-First Modunu kullanın. API sözleşmelerini çekme isteklerinde (pull requests) inceliyorsanız, spesifikasyonun hizmet kodunuzun yanında sürümlemesini istiyorsanız veya mühendisleriniz doğrudan YAML düzenlemeyi tercih ediyorsa, bu mod sürtünmeyi ortadan kaldırır. OpenAPI belgesini birinci sınıf bir yapıt olarak gören backend ve platform ekipleri için güçlü bir uyum sağlar.

Rehberli, görsel bir deneyim istiyorsanız bunun yerine Design-First Modunu seçin. Tasarım katkısı yapan mühendis olmayan ekipler veya YAML yazmak yerine formlara tıklamayı tercih eden herkes orada daha hızlı ilerleyecektir. Ürün ve tasarımın uç noktalar üzerinde söz sahibi olduğu karma ekipler genellikle görsel düzenleyiciyi tercih eder. Yanlış bir cevap yoktur. Ekibinizin gerçekte nasıl çalıştığına uyan modu seçin. Karşılaştırma yazımız bu kararı daha derinlemesine ele alır.

Sınırlamalar ve Beta Notları

Spec-First Modu bir beta özelliğidir. Bu kelime gerçek bir işlevi ifade ediyor, bu yüzden beklentilerinizi buna göre ayarlayın.

Bir beta olarak, özellik hala olgunlaşmaktadır. Apidog, geri bildirimlere dayanarak modu geliştirdikçe yetenekler ve davranışlar değişebilir. Doğrudan sağlayıcı entegrasyonu bugün GitHub ve GitLab'ı kapsarken, Azure DevOps özel bir entegrasyon yerine genel Git Bağlantısı'na dayanmaktadır. Ekibiniz belirli bir Git sağlayıcısına veya iş akışına bağlıysa, kritik bir projeyi bu moda başlamadan önce ihtiyaçlarınızı karşıladığından emin olun.

Spesifikasyon canlı bir depoyla senkronize olduğu için normal Git disiplini geçerlidir. Bilinçli bir şekilde kaydedin (commit), kasıtlı olarak gönderin (push) ve bir düzenlemenin yayınlanmaması gerektiğinde atma (discard) seçeneğini kullanın. Dosya değişikliği takibi ve senkronizasyon göstergesi sizi güvende tutmak için oradadır, ancak temiz geçmişin sorumluluğu hala sizdedir. Betayı, ana dalınıza dokunan herhangi bir yeni araca davrandığınız gibi ele alın: önce kritik olmayan bir depoda deneyin, ardından akışa güvendiğinizde genişletin.

Bir betanın avantajı, etkileme gücüdür. Erken geri bildirimler özelliğin nereye gittiğini şekillendirir, bu nedenle iş akışınız için bir şey eksikse, bunu rapor etmeye değerdir.

SSS (Sıkça Sorulan Sorular)

Spec-First Modu Ücretsiz mi?

Spec-First Modu, Apidog içinde bir beta özelliğidir. Erişiminiz Apidog planınıza göre belirlenir, bu nedenle modun kullanılabilirliğini mevcut planınız ve beta durumuyla karşılaştırın. Beta aşamasında olduğu için, en basit yol onu API'ler modülünde etkinleştirip hesabınız için uygun olup olmadığını görmektir.

Hangi Git Sağlayıcıları Destekleniyor?

GitHub ve GitLab doğrudan entegrasyon aracılığıyla desteklenir. Azure DevOps, Apidog'u deponuza yönlendirmek için standart Git kimlik bilgilerini kullanan genel bir Git Bağlantısı aracılığıyla çalışır. Diğer Git sunucuları da bu genel bağlantı aracılığıyla çalışabilir, çünkü sağlayıcıya özel bir API yerine standart Git'e dayanır.

Design-First Modu'na Geri Dönebilir miyim?

Evet. Mod düğmesi API'ler modülünün sol altında yer alır ve Spec-First ile Design-First arasında orada geçiş yaparsınız. Kilitli kalmazsınız. Önünüzdeki projeye uygun olan modu seçin.

Hangi Dosya Formatlarını Düzenleyebilirim?

OpenAPI belgenizi IDE tarzı düzenleyicide ham YAML veya JSON olarak düzenlersiniz. Düzenleyici, hem OpenAPI hem de Swagger için sözdizimi vurgulaması, şema doğrulaması ve otomatik tamamlama sağlar, böylece herhangi bir formatta yazarken doğru kalırsınız.

Gönderilmemiş Düzenlemelerime Ne Olur?

Gönderilmemiş (unpushed) düzenlemeler, siz onları gönderene (push) kadar yerel kalır. Spec-First Modu her değişikliği değiştirilmiş, eklenmiş veya silinmiş olarak izler ve senkronizasyon göstergesi, depoya ulaşmamış işiniz olduğunda gösterir. Bir değişiklikten vazgeçerseniz, göndermeden (push) önce onu atın ve paylaşılan geçmişinize asla girmez.

Sonuç

Apidog Spec-First Modu, OpenAPI düzenleyiciyi ve Git'i tek bir yerde bir araya getirir. Spesifikasyonu YAML veya JSON olarak düzenler, otomatik olarak ayrıştırılmış bir taslak aracılığıyla gezersiniz, yazarken doğrularsınız ve GitHub, GitLab veya Azure DevOps ile çift yönlü olarak senkronize edersiniz. Commit mesajları, gönderme (push), değişiklik takibi ve açık bir senkronizasyon göstergesi, API sözleşmenize uygulanan, zaten bildiğiniz Git iş akışını size sunar.

Bir beta sürümüdür ve spesifikasyonun kaynak kodu olmasını isteyen Git-yerel ekipleri hedefler. Eğer bu sizseniz, mod ciddi bir bakışa değer. Onu API'ler modülünde etkinleştirin, bir depo bağlayın ve akışı hissetmek için küçük bir düzenle-kaydet-gönder (edit-commit-push) döngüsü deneyin. Hazır olduğunuzda, belgelerde Spec-First Modu'nu deneyin ve güvendiğiniz bir depoya bağlayın.