Apidog'un API'ler modülü, aynı şeyi oluşturmanın iki yolunu sunar: bir API sözleşmesi. Biri görsel formlar kullanır. Diğeri ise Git'e bağlı ham bir kod düzenleyici kullanır. Her ikisi de geçerli OpenAPI üretir. Fark, ekibinizin günlük olarak nasıl çalıştığı ve hangisinin uygun olduğunun araca değil, alışkanlıklarınıza daha az bağlı olmasıdır.
Bu kılavuz, Apidog'da tasarım öncelikli (design-first) ve spesifikasyon öncelikli (spec-first) kararını ele almaktadır: her modun ne olduğu, Git'i nasıl yönettikleri ve hangi ekiplerin hangisini tercih ettiği. API'ler modülünün sol alt köşesindeki tek bir düğmeden bunlar arasında geçiş yapabilirsiniz, bu yüzden seçim kalıcı değildir. Ancak doğru varsayılanı seçmek sürtünmeyi azaltır.
İki felsefe
Modlardan önce, zihniyet. Her iki yaklaşım da tek bir kuralı paylaşır: uygulamayı yazmadan önce API sözleşmesini tanımlarsınız. Sözleşme, gerçekliğin kaynağıdır. Kod, testler, maketler ve belgeler hepsi ondan türemiştir.
Tasarım öncelikli (Design-first), bu sözleşmeyi yapılandırılmış bir arayüz aracılığıyla şekillendirmeniz anlamına gelir. Formlar ve açılır menüler aracılığıyla uç noktalar, parametreler ve şemalar eklersiniz. Araç, çıktının geçerli olduğunu garanti eder çünkü yalnızca geçerli değerler girebilirsiniz.
Spesifikasyon öncelikli (Spec-first) (genellikle sözleşme öncelikli olarak adlandırılır), sözleşmeyi doğrudan bir spesifikasyon dosyası olarak yazmanız anlamına gelir: YAML veya JSON formatında OpenAPI. Spesifikasyon, sizin çalışma yüzeyinizdir. Onu kaynak kod gibi düzenlersiniz.
Bu terimler pratikte üst üste biner. "Sözleşme öncelikli" ve "spesifikasyon öncelikli" neredeyse eş anlamlıdır ve birçok ekip "tasarım öncelikli" terimini, sözleşmenin koda öncelik verdiği herhangi bir yaklaşımı gevşekçe ifade etmek için kullanır. Buradaki kullanışlı ayrım somuttur: Apidog'da bir mod size formlar sunarken, diğeri size bir metin düzenleyici sunar. Seçim yaparken önemli olan çizgi budur.
Bunların her ikisini de tasarım öncelikli (design-first) ve kod öncelikli (code-first) API geliştirmeden ayırmaya değer. Kod öncelikli, spesifikasyonu uygulamanızdaki açıklamalardan üretir, bu yüzden kod öndedir. Her iki Apidog modu da sözleşmeyi kodun önünde tutar. Sadece onu nasıl yazdığınız konusunda ayrışırlar. Spesifikasyonunuzu sürümlü bir yapıt olarak ele almanın daha geniş resmi için, Git-yerel API iş akışına genel bakışımıza bakın.
Apidog Tasarım Öncelikli Modu
Tasarım Öncelikli Mod, görsel tasarımcıdır. Yönlendirmeli bir arayüz aracılığıyla uç noktalar oluşturursunuz: bir yöntem seçer, yolu adlandırır, sorgu ve yol parametreleri ekler, bir ağaç düzenleyici aracılığıyla istek ve yanıt şemalarını tanımlar ve örnekler eklersiniz. Apidog, arka planda sizin için temel OpenAPI'yi oluşturur.
Bu mod, çoğu ekip için varsayılandır ve bunun iyi bir nedeni vardır. OpenAPI sözdizimini hatırlamanıza gerek kalmaz. Şema düzenleyici yapıyı zorlar, bu nedenle yanlış yerleştirilmiş bir köşeli parantez veya geçersiz bir tür içeren bir spesifikasyon gönderemezsiniz. Paylaşılan bir Error şeması veya ortak bir başlık gibi yeniden kullanılabilir bileşenler birkaç tıklama ile erişilebilir.
Tasarım Öncelikli Mod ayrıca dalları da destekler, böylece ekipler API tasarımının ayrı versiyonları üzerinde paralel olarak çalışabilir ve bunları daha sonra uzlaştırabilir. Gözden geçirenler, ham metin yerine yapılandırılmış bir fark görürler, bu da YAML'de yaşamayan insanlar için sözleşme değişikliklerini okumayı kolaylaştırır.
Dezavantajı: bir soyutlama aracılığıyla çalışıyorsunuz. Eğer zaten OpenAPI düşünüyorsanız, formlar sizinle kafanızdaki spesifikasyon arasında ek tıklamalar gibi hissettirebilir.
Apidog Spesifikasyon Öncelikli Mod
Şu anda beta aşamasında olan Spesifikasyon Öncelikli Mod, bunu tersine çevirir. Formlar yerine, bir IDE tarzı kod düzenleyici alırsınız ve OpenAPI veya Swagger spesifikasyonunu doğrudan YAML veya JSON olarak yazarsınız. API tanımının, diğer tüm kaynak dosyaları gibi Git'te yaşamasını isteyen ekipler için tasarlanmıştır.
Düzenleyici, kod düzenleyicinizdeki gibi davranır: sözdizimi vurgulama, satır içi doğrulama ve OpenAPI ve Swagger şemaları için ayarlanmış otomatik tamamlama. Siz yazarken, sol kenar çubuğu spesifikasyonunuzu otomatik olarak yollar ve bileşenlerin bir taslağına ayrıştırır, böylece büyük bir dosyada kaydırma yapmadan gezinebilirsiniz. Bir senkronizasyon göstergesi, yerel düzenlemelerinizin bağlı depoyla uyumlu olup olmadığını gösterir.
Başlık iki yönlü Git senkronizasyonuna sahiptir. GitHub veya GitLab'da bir depo bağlarsınız (Azure DevOps, genel bir Git Bağlantısı aracılığıyla çalışır) ve Apidog, spesifikasyon dosyanızı her iki yönde senkronize eder. Apidog'da düzenleyin, ardından doğrudan uygulamadan commit edin ve push edin. Veya spesifikasyonu kod düzenleyicinizde düzenleyin, oradan push edin ve değişiklikleri Apidog'a geri çekin. Spesifikasyon dosyası paylaşılan gerçektir ve her iki yüzey de hizalı kalır. Tam kurulumu Spesifikasyon Öncelikli Mod belgelerinde okuyabilirsiniz.
Bu mod, API sözleşmenizi diğer herhangi bir kod yapıtına davrandığınız gibi ele alır: çekme isteklerinde incelenir, onu uygulayan hizmetlerle birlikte sürümlendirilir ve satır satır karşılaştırılır. Eğer ekibiniz zaten altyapıyı ve yapılandırmayı bu şekilde yönetiyorsa, bunun arkasındaki mantık için kod olarak API spesifikasyonu hakkındaki derinlemesine makalemize bakın.
Yan yana karşılaştırma
Her iki mod da aynı OpenAPI'yi üretir ve aşağı akışta maket oluşturma, test etme ve belgelemeyi destekler. Spesifikasyonu nasıl yazdığınız ve sürümlendirdiğiniz konusunda farklılık gösterirler.
| Tasarım Öncelikli Mod | Spesifikasyon Öncelikli Mod (beta) | |
|---|---|---|
| Düzenleyici | Görsel formlar ve şema ağacı | IDE tarzı YAML/JSON kod düzenleyici |
| Spesifikasyon formatı | OpenAPI (sizin için oluşturulur) | OpenAPI / Swagger, elle yazılır |
| Git iş akışı | Apidog içinde dal desteği | GitHub, GitLab, Azure DevOps (Git Bağlantısı) ile iki yönlü senkronizasyon; uygulamadan commit etme ve push etme |
| Doğrulama | Form girişleriyle zorlanır | Satır içi sözdizimi doğrulama ve otomatik tamamlama |
| Navigasyon | Uç nokta listesi ve klasörler | Sol kenar çubuğunda otomatik ayrıştırılmış taslak |
| Öğrenme eğrisi | Düşük; OpenAPI bilgisi gerekmez | Daha yüksek; OpenAPI akıcılığı gerektirir |
| En iyi kimler için | Karışık yetenekli ekipler, hızlı başlangıç | Spesifikasyonu kod olarak gören mühendisler |
Hangi ekip hangisini seçmeli
Katkıda bulunanlarınızın hepsi OpenAPI uzmanı değilse Tasarım Öncelikli Mod'u kullanın. Ürün yöneticileri, QA ve genç mühendisler, spesifikasyon sözdizimini öğrenmeden uç noktaları ekleyebilir veya gözden geçirebilirler. Ayrıca, sıfırdan yeni bir API başlattığınızda ve biçimlendirme konusunda endişelenmeden yapı üzerinden hızla ilerlemek istediğinizde daha hızlı bir yoldur.
Spesifikasyonunuz halihazırda veya hizmet kodunuzun yanında bir Git deposunda yaşaması gerekiyorsa Spesifikasyon Öncelikli Mod'u kullanın. Çekme isteklerinde API değişikliklerini gözden geçiren, CI'da spesifikasyon denetimi yapan veya araçlar arasında tek bir standart YAML dosyası isteyen arka uç ekipleri kendilerini evlerinde hissedeceklerdir. İki yönlü senkronizasyon, Apidog'un ayrı bir gerçek kopyası olmaktan çıkıp, deponuzun tuttuğu aynı dosyaya bir pencere haline gelmesi anlamına gelir.
Pratik bir orta yol: birçok ekip, hız için yeni uç noktaları Tasarım Öncelikli Mod'da tasarlar, ardından API olgunlaştığında ve Git incelemesi öncelik haline geldiğinde Spesifikasyon Öncelikli Mod'a geçer. Modlar rakip ürünler değildir. Tek bir sözleşmenin iki görünümüdürler.
Modlar nasıl değiştirilir
Geçiş tek bir düğme ile yapılır. Apidog projenizdeki API'ler modülünü açın ve mod değiştiricinin bulunduğu sol alt köşeye bakın. Düğmeye basın, aynı sözleşme diğer modda görüntülenir.
Geçiş yaparken akılda tutulması gereken birkaç şey:
- Temel spesifikasyon paylaşıldığı için uç noktalarınız, şemalarınız ve örnekleriniz aktarılır. Düzenleme yüzeyini değiştiriyorsunuz, API'yi yeniden inşa etmiyorsunuz.
- Spesifikasyon Öncelikli Mod'un Git senkronizasyonunu kullanmak için önce GitHub, GitLab veya Azure DevOps deponuzu bağlayın. Bağlandıktan sonra, senkronizasyon göstergesi düzenlemelerinizin commit edilip push edilmediğini size söyler.
- Spesifikasyon Öncelikli Mod beta aşamasında olduğu için, üretim sözleşmesi için ona güvenmeden önce senkronizasyon davranışını doğrulayabileceğiniz bir projede deneyin.
İhtiyaçlarınız değiştikçe ileri geri hareket edebilirsiniz, bu nedenle seçimi kalıcı bir taahhüt yerine bir varsayılan olarak kabul edin.
SSS
Spesifikasyon öncelikli, sözleşme öncelikli ile aynı mı?
Pratikte evet. "Spesifikasyon öncelikli" ve "sözleşme öncelikli" her ikisi de uygulamadan önce API spesifikasyonunu yazdığınız ve her ikisi de bu spesifikasyonu doğruluk kaynağı olarak kabul ettiğiniz anlamına gelir. Apidog'un Spesifikasyon Öncelikli Modu, sözleşmenin Git ile senkronize edilmiş el yazısıyla yazılmış bir OpenAPI veya Swagger dosyası olduğu sözleşme öncelikli bir iş akışıdır.
Spesifikasyon Öncelikli Mod, GitLab ve Azure DevOps ile çalışır mı?
Evet. Spesifikasyon Öncelikli Mod, GitHub ve GitLab ile doğrudan iki yönlü Git senkronizasyonunu destekler. Azure DevOps, genel bir Git Bağlantısı aracılığıyla çalışır, böylece spesifikasyon dosyanızı Azure'da barındırılan bir depoya da senkronize edebilirsiniz.
Tasarım öncelikliden spesifikasyon öncelikliye geçiş yaparken işimi kaybetmeden geçiş yapabilir miyim?
Evet. Her iki mod da aynı temel sözleşmeyi okur ve yazar, bu nedenle API'ler modülünün sol altındaki düğmeyi çevirdiğinizde uç noktalarınız, şemalarınız ve örnekleriniz bozulmadan kalır. Düzenleyiciyi değiştiriyorsunuz, veriyi değil.
Ekibinize hangisinin uygun olduğundan emin değil misiniz? API'ler modülünü açın, sol alttaki mod geçişini deneyin ve bir sonraki uç noktanızı her iki şekilde de tasarlayın. Sözleşme her iki şekilde de aynıdır; ekibinizin halihazırda çalıştığı yüzeyi seçin.