Çalıştığım her API ekibinde iki farklı taraf vardı.
Bir taraf, OpenAPI spesifikasyonlarını elle yazar, bir specs/ dizinine kaydeder ve Git'i tek doğruluk kaynağı olarak kabul eder. Diğer taraf ise görsel bir tasarımcı üzerinden ilerler, CI şikayet ettiğinde spesifikasyonu dışa aktarır ve iki temsil arasındaki geçen Salı'dan bu yana biriken tutarsızlıkları düzeltir.
Her iki tarafta da bulundum. İlk taraf ilk gün daha yavaş, doksanıncı gün ise daha hızlıdır. İkincisi tam tersidir. Ve yaklaşık bir ay öncesine kadar, en çok kullandığım API tasarım aracı olan Apidog, sadece ikinci tarafa hitap ediyordu. Görsel tasarımcısı mükemmeldi. YAML çift yönlü dönüşümü, kod incelemesinde savunmanız gereken bir özellikti.
Ardından Nisan ortasında, Spec-First Modu (Beta) Yeni Proje iletişim kutusunda belirdi. Lansman gününde kasıtlı olarak yazmadım. Önce gerçek bir şey üzerinde kullanmak istedim ve ilk haftaki hataların ortaya çıkması için yeterince beklemek istedim. Bir ay yaklaşık olarak doğru süredir. Bu yazı, yan projelerimden birindeki bir OpenAPI spesifikasyonuyla betayı bir sabah geçirdikten sonra bulduklarımı anlatıyor – bir takım arkadaşıma denemeden önce ne söyleyeceğimi ve nerede uygun olup nerede olmadığını.
Spec-First Modu aslında neyi değiştiriyor
Kısa versiyonu: Apidog artık iki proje moduna sahip ve bunlar aslında altta yatan farklı ürünler.
Varsayılan mod çoğu kişinin bildiği moddur. + Yeni Proje'ye tıklarsınız, bir klasör ağacı ve görsel formlar elde edersiniz ve alanları doldurarak uç noktalar oluşturursunuz. OpenAPI spesifikasyonu arka planda oluşturulur. Özellikle güçlü bir YAML alışkanlığı olmayan ekipler için işe yarar.
Spec-First Modu, form düzenleyiciyi ham .yaml ve .json dosyaları üzerinde gerçek bir kod düzenleyiciyle ve Git deponuzla çift yönlü bir senkronizasyonla değiştirir. OpenAPI spesifikasyonunuz, tıklamaların serileştirilmesi değil, diskinizdeki dosyadır. Sözdizimi vurgulama, OpenAPI şemasına göre otomatik tamamlama ve siz yazdıkça kodunuzdan kenar çubuğunda bir uç nokta taslağı oluşturan "Gerçek Zamanlı Dizin Ayrıştırma" paneli bulunur.
Şüpheci birine bunu gösteriyor olsaydım, son detay benim öne çıkacağım şey olurdu. Görsel tasarımcıların var olma nedeni YAML'ın zor olması değil; YAML'ın, siz zaten onu geçinceye kadar yapıyı gizlemesidir. Apidog'un taslak görünümü, dosyadan vazgeçmek zorunda kalmadan bunu çözer. Spesifikasyon yazarsınız, gezinme elde edersiniz. İkisi ekranda bir arada bulunur.
Tez, eğer varsa: spesifikasyon öncelikli geliştirme hiçbir zaman metin düzenleyicileri tercih etmekle ilgili değildi. Yapıtın kime ait olduğuyla ilgiliydi. Spec-First Modu, yapıtı deponuzdaki dosya yapar, hepsi bu. Kullanıcı arayüzü, etrafındaki bir sarmalayıcı değil, ona açılan bir penceredir.
Uçtan uca kurulum
İşte izlediğim yol. On dakikadan az sürdü, çoğu Git yetkilendirmesiydi.
1. Projeyi doğru modda oluşturun. Projeler ekranından, + Yeni Proje → Genel → Spec-first Modu. Bir yıldır otomatik pilotta proje oluşturuyorsanız mod seçiciyi kaçırmak kolaydır — Genel Mod "Önerilen" olarak işaretlidir ve gözünüz ikinci kutucuğun üzerinden kayar. Burada yavaşlayın.
2. Git deponuza bağlanın. Git Deposu ile Bağlan seçeneğine gidin ve sağlayıcınızı yetkilendirin. GitHub kullandım; belgeler diğerlerini kapsıyor. Sonra Organizasyon, Depo ve Ana dalı seçin. Apidog, o daldaki spesifikasyon dosyalarını çalışma kopyanız olarak senkronize edecektir.
3. Projeyi yapılandırın. Bir Proje Adı girin, ekip izinlerini ayarlayın ve Oluştur'a tıklayın. İlk senkronizasyon, depoda bulunan tüm .yaml ve .json dosyalarını Apidog'un çalışma alanına çeker.
4. Spesifikasyonu form olarak değil, dosya olarak düzenleyin. YAML dosyalarından birini açın. Gerçek bir düzenleyici, şemaya duyarlı otomatik tamamlama ve siz yazdıkça kenar çubuğunda beliren uç nokta taslağı elde edersiniz. Eğer VS Code'da OpenAPI uzantısıyla biraz zaman geçirdiyseniz, bu size tanıdık gelecektir — sadece taslak gezinmeye bağlıdır ve bir uç noktaya tıklamak doğru satıra atlar.
5. Commit edin ve push edin. Sağ üstte, Commit & Push. İletişim kutusu, değiştirilmiş dosyaları listeleyen bir Değişiklikler bölümü, bir Commit Mesajı alanı ve iki düğme ile açılır: Push veya Tüm değişiklikleri iptal et. Ayrı bir hazırlık adımı yoktur — Değişiklikler'deki her şey commit'e gidecektir. Bu bilinçli bir basitleştirmedir ve çoğu spesifikasyon düzenleme iş akışı için doğru karardır.
6. Senkronizasyon göstergesini izleyin. Sol alt köşede — Şekil 1'de Şimdi senkronize edildi olarak görebilirsiniz. Yerel düzenlemelerinizin push mu, pull mu edildiğini veya uzaktan senkronizasyon dışı mı olduğunu size bildirir. Bunu ekranımın bir köşesinde açık bıraktım ve modal iletişim kutularından daha çok güvendiğim şey bu oldu. Gösterge yeşilse, siz ve depo aynı fikirdesiniz demektir.
Tüm yüzey alanı bu. Altı adım, yapılandırılacak ayrı bir senkronizasyon motoru yok, yüklenecek eklenti yok.
Belgelerin size söylemediği fark ettiğim şeyler
Üç önemli nokta var, hepsi bir sabah kurcaladıktan sonra ortaya çıktı.
Ana hat görünümü beklediğimden daha hızlı güncelleniyor. Geçmişte birkaç "canlı OpenAPI düzenleyici" kullandım ve çoğu kaydederken yeniden ayrıştırır, bu da bir uç nokta eklemek ile kenar çubuğunda görmek arasında 30 saniyelik bir gecikme anlamına gelir. Apidog'un ana hat görünümü ben yazdıkça güncellendi — anında denecek kadar hızlıydı ki kontrol etmeyi bıraktım. Kulağa küçük bir şey gibi geliyor. Değil. Bu, ana hattı bir gezinme yardımı olarak güvenmek ile onu bir durum raporu olarak kontrol etmek arasındaki farktır.
Git entegrasyonu gerçekten çift yönlüdür. Apidog açıkken yerel klonumdaki aynı dosyayı düzenledim ve terminalden push ettim. Apidog fark etti, senkronizasyon göstergesi "geride" durumuna geçti ve tek tıklamayla değişiklikler birleştirme iletişim kutusu olmadan düzenleyiciye çekildi. Belgelerin vaat ettiği çift yönlü senkronizasyon, bir pazarlama özeti değil, gerçek bir deneyimdir. Eğer Vim'den başka hiçbir şey kullanmayı reddeden bir takım arkadaşınız varsa, o Vim kullanmaya devam edebilir ve siz Apidog kullanmaya devam edebilirsiniz ve depodaki dosya ikinizin de düzenlediği tek şey olmaya devam eder.
Aynı projede görsel tasarımcıya geri dönüş için bir kaçış yolu yok. Bu kasıtlıdır, ancak taahhüt etmeden önce bilmeye değer. Oluşturma sırasında Spec-First Modu'nu seçerseniz, o proje spec-first olur. Veri modelleri farklı olduğu için bir projeyi yarı yolda değiştiremezsiniz. Aynı spesifikasyonda her iki modu da isteyen bir ekip için iş akışı şöyledir: spesifikasyonu bir depoda tutun, ona bir Spec-First projesi işaret edin ve görsel mod kullanıcılarının aynı kaynaktan içe aktaran ayrı bir proje açmasına izin verin. Sorunsuz değil ama uygulanabilir.
Nerede uyuyor, nerede uymuyor
Bunu üretimde kullanacağım. Verebileceğim en doğrudan cevap bu. Gerçek bir düzenleyici, OpenAPI şemasına uyan otomatik tamamlama ve güvenebileceğim bir senkronizasyon göstergesinin birleşimi, Apidog'dan iki yıldır istediğim şeydi.
Ama bu, kimler için olduğuyla ilgili dürüst versiyonu.
Eğer zaten OpenAPI'yi elle yazıyorsanız veya yazmak istiyorsanız uyar. Eğer CI'niz spectral lint çalıştırıyorsa veya spesifikasyondan istemci SDK'ları oluşturuyorsa ve spesifikasyonun Git'te olması gerekiyorsa uyar. Eğer ekibinizde VS Code'dan YAML dosyasına karşı pull request açacak bir mühendis varsa ve herkesi klavyelerinden vazgeçirmeden tek bir araç üzerinde birleştirmek istiyorsanız uyar. Ve özellikle "Apidog'daki spesifikasyon" ile "depodaki spesifikasyon" arasındaki kaymayı kimsenin güvenmediği bir make export adımıyla yönetiyorsanız çok iyi uyar.
Eğer ekibiniz hiç OpenAPI'ye dokunmadıysa ve görsel tasarımcı onların katkıda bulunmasının nedeni ise, bu uygun değildir. Bu tür ekipler için varsayılan mod hala doğru seçimdir. Spec-First Modu, başlangıç kolaylığını doğrulukla takas eder ve katkıda bulunanların çoğu API uzmanı olmadığında bu takas yanlıştır.
Ayrıca, aynı proje üzerinde her iki modu da karıştırması gereken ekipler için henüz uygun değil. Beta bu konuda gerçekten bir beta. Sonraki birkaç sürümde bunun yumuşayacağını beklerdim.
Sonuç
Spesifikasyon öncelikli geliştirme, API tasarım araçlarından vazgeçmek anlamına geliyordu. Ya YAML'de yaşar, test koşucularından ve sahte sunuculardan vazgeçerdiniz ya da görsel bir tasarımcıda yaşar, Git'i tek doğruluk kaynağı olarak kabul etmekten vazgeçerdiniz. Spec-First Modu'ndaki ilginç hareket, Apidog'un sizi seçmeye zorlamayı bırakmasıdır.
Deponuzdaki dosya, düzenleyicinizdeki dosyadır. Ana hat bir görünüm, bir durum değildir. Git senkronizasyonu bir özellik değil, bir bağlantıdır. Eğer bir API platformunun spesifikasyon öncelikliliği, bir dışa aktarma seçeneği olarak ele almak yerine ciddiye almasını bekliyorsanız, deneyeceğim platform budur.
Beta bugün Yeni Proje iletişim kutusunda canlı. Apidog'u indirin, oluştururken Spec-First Modu'nu seçin ve güvenli bir depoya işaret edin. İlk commit on dakika sürer. Kalıp kalmayacağına karar vermek ise yaklaşık bir hafta alır.
düğme