Apidog Spec-First Modu ile Bir Sabah: Görsel Tasarımcı Artık Tek Yetkili Değil

Çalıştığım her API ekibinde aynı ayrım vardı: OpenAPI dosyasını Git’te tek doğruluk kaynağı yapanlar ve görsel tasarım aracı üzerinden ilerleyip gerektiğinde spesifikasyon dışa aktaranlar.

Apidog'u bugün deneyin

İlk yaklaşım başlangıçta daha yavaştır ama uzun vadede daha öngörülebilirdir. İkincisi hızlı başlatır; ancak zamanla “araçtaki API” ile “depodaki OpenAPI dosyası” arasında fark oluşabilir.

Apidog uzun süre daha çok ikinci akışa uygundu: güçlü bir görsel tasarımcı, dokümantasyon, test ve mock özellikleri vardı; fakat YAML/JSON dosyasını doğrudan Git merkezli yönetmek isteyen ekipler için akış tam oturmuyordu.

Nisan ortasında Spec-First Modu (Beta), Yeni Proje ekranına eklendi. Bir yan projemdeki OpenAPI spesifikasyonuyla denedim. Bu yazıda, Spec-First Modu’nun pratikte ne değiştirdiğini, nasıl kurulduğunu ve hangi ekipler için anlamlı olduğunu anlatıyorum.

Spec-First Modu neyi değiştiriyor?

Apidog artık iki farklı proje akışı sunuyor:

• Genel Mod: Uç noktaları görsel formlarla tasarlarsınız. OpenAPI çıktısı arka planda oluşur.
• Spec-First Modu: OpenAPI dosyası doğrudan .yaml veya .json olarak düzenlenir. Git deposu dosyanın ana kaynağıdır.

Spec-First Modu’nda Apidog, form tabanlı düzenleyicinin yerine kod düzenleyici verir:

• OpenAPI şemasına göre otomatik tamamlama
• Sözdizimi vurgulama
• Dosyadan gerçek zamanlı uç nokta taslağı çıkarma
• Git deposuyla çift yönlü senkronizasyon
• Commit ve push işlemlerini arayüzden yapma

Buradaki temel fark şu: Spesifikasyon artık görsel arayüzün ürettiği bir çıktı değil, deponuzdaki dosyanın kendisi.

Bu özellikle OpenAPI’yi elle yazan ekipler için önemli. YAML dosyası üzerinde çalışırken yapı bazen gözden kaçar. Apidog’un sol taraftaki canlı taslak görünümü, dosyayı bırakmadan gezinmeyi kolaylaştırır. Spesifikasyonu yazarsınız; Apidog aynı anda endpoint ağacını çıkarır.

Uçtan uca kurulum

Aşağıdaki akışla mevcut bir Git deposundaki OpenAPI dosyasını Apidog Spec-First projesi olarak açabilirsiniz.

1. Yeni projeyi Spec-First Modu ile oluşturun

Apidog’da:

+ Yeni Proje → Genel → Spec-first Modu

Genel Mod varsayılan olarak öne çıkarıldığı için bu ekranda doğru kutucuğu seçtiğinizden emin olun. Spec-First Modu beta etiketiyle görünür.

2. Git deponuzu bağlayın

Ardından Git Deposu ile Bağlan seçeneğini kullanın.

Seçmeniz gerekenler:

• Organizasyon
• Depo
• Ana dal

Örneğin:

Organizasyon: my-org
Depo: petstore-api
Ana dal: main

Apidog, seçilen daldaki .yaml ve .json dosyalarını çalışma alanına senkronize eder.

3. Proje ayarlarını tamamlayın

Bir proje adı girin, ekip erişimlerini ayarlayın ve Oluştur düğmesine tıklayın.

İlk senkronizasyonda depodaki OpenAPI dosyaları Apidog çalışma alanına alınır.

4. Spesifikasyonu dosya olarak düzenleyin

Bir OpenAPI YAML dosyası açın.

Örneğin aşağıdaki gibi bir endpoint eklediğinizde:

paths:
  /orders/{orderId}:
    get:
      summary: Sipariş detayını getir
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Başarılı yanıt

Apidog, sol taraftaki taslak görünümde ilgili route’u otomatik olarak gösterir. Endpoint’e tıkladığınızda dosyadaki ilgili satıra gidersiniz.

VS Code’da OpenAPI uzantılarıyla çalışmaya alışkınsanız deneyim tanıdık gelir. Fark, Apidog’un aynı çalışma alanında API dokümantasyonu, test ve proje görünümünü de sağlamasıdır.

5. Commit ve push yapın

Sağ üstten Commit & Push düğmesine tıklayın.

Açılan pencerede:

• Değişen dosyaları görürsünüz
• Commit mesajı yazarsınız
• Push işlemini başlatırsınız

Örnek commit mesajı:

Add order detail endpoint to OpenAPI spec

Ayrı bir staging adımı yoktur. Değişiklikler bölümündeki dosyalar commit’e dahil edilir.

6. Senkronizasyon durumunu kontrol edin

Sol alt köşedeki senkronizasyon göstergesini takip edin.

Duruma göre şunu anlarsınız:

• Yerel değişiklikler push edilmeyi bekliyor mu?
• Uzak depo sizden ileride mi?
• Çalışma alanı depoyla aynı durumda mı?

Gösterge “Şimdi senkronize edildi” durumundaysa Apidog’daki dosya ve Git deposundaki dosya aynı noktadadır.

Deneyimde öne çıkan noktalar

Canlı endpoint taslağı hızlı çalışıyor

Bazı OpenAPI düzenleyicilerinde kenar çubuğu yalnızca dosya kaydedildiğinde veya belirli aralıklarla güncellenir. Burada endpoint taslağı yazarken güncellendi.

Bu küçük görünse de pratikte önemli. Büyük bir OpenAPI dosyasında çalışırken sol taraftaki yapı görünümünü gerçek navigasyon aracı olarak kullanabiliyorsunuz.

Git entegrasyonu çift yönlü

Apidog açıkken aynı dosyada yerel klondan değişiklik yapıp terminalden push ettiğinizde Apidog bunu algılıyor. Senkronizasyon durumu değişiyor ve uzaktaki güncellemeler çalışma alanına alınabiliyor.

Bu, karma ekipler için kullanışlı:

• Bir geliştirici Vim veya VS Code ile çalışabilir
• Başka biri Apidog arayüzünü kullanabilir
• İkisi de aynı Git deposundaki OpenAPI dosyasını günceller

Tek doğruluk kaynağı yine depo olur.

Proje modu sonradan değiştirilemiyor

Spec-First Modu’nda oluşturulan proje, aynı proje içinde Genel Mod’a dönmüyor. Bu bilinçli bir ayrım; çünkü veri modeli ve çalışma şekli farklı.

Aynı spesifikasyon için iki akışa ihtiyaç varsa uygulanabilir seçenek şu:

1. OpenAPI dosyasını Git deposunda tutun.
2. Bu depoyu bir Spec-First projesine bağlayın.
3. Görsel mod kullanacak ekipler için aynı kaynaktan ayrı bir proje oluşturun.

Bu tamamen sorunsuz bir geçiş değil; ancak tek dosya kaynağını korumak isteyen ekipler için uygulanabilir.

Ne zaman kullanmalı?

Spec-First Modu şu durumlarda iyi uyuyor:

• OpenAPI dosyalarını zaten elle yazıyorsanız
• Spesifikasyonun Git’te kalması gerekiyorsa
• CI sürecinizde spectral lint gibi kontroller varsa
• SDK veya dokümantasyon üretimini OpenAPI dosyasından yapıyorsanız
• Pull request üzerinden API değişikliği incelemek istiyorsanız
• “Apidog’daki spec” ile “depodaki spec” arasında fark oluşmasını istemiyorsanız

Örnek CI akışı şöyle olabilir:

name: OpenAPI checks

on:
  pull_request:
    paths:
      - "openapi/**/*.yaml"

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI spec
        run: npx @stoplight/spectral-cli lint openapi/api.yaml

Bu tarz bir akışta Spec-First Modu anlamlıdır; çünkü Apidog’da yaptığınız değişiklikler doğrudan Git’teki dosyaya commit edilir.

Ne zaman kullanmamalı?

Aşağıdaki durumlarda Genel Mod daha doğru olabilir:

• Ekibiniz OpenAPI yazmaya alışık değilse
• Katkı verecek kişiler YAML/JSON düzenlemek istemiyorsa
• Görsel formlar ekip için ana üretim aracıysa
• Aynı proje içinde sürekli görsel mod ve spec-first mod arasında geçiş yapmanız gerekiyorsa

Spec-First Modu, kullanım kolaylığının bir kısmını doğruluk ve Git merkezli çalışma karşılığında takas eder. API uzmanlığı az olan ekiplerde bu takas her zaman doğru olmayabilir.

Sonuç

Spec-first geliştirme genelde şu ikileme sıkışıyordu:

• Ya OpenAPI dosyasında yaşayıp API platformunun görsel özelliklerinden uzak kalırsınız
• Ya da görsel tasarımcıda çalışıp Git’teki dosyayı ikincil çıktı haline getirirsiniz

Apidog Spec-First Modu bu ayrımı azaltıyor. Deponuzdaki OpenAPI dosyası çalışma alanının merkezinde kalıyor; Apidog ise bu dosyanın üzerinde düzenleme, gezinme ve Git senkronizasyonu sağlayan bir arayüz oluyor.

OpenAPI’yi Git’te tek doğruluk kaynağı olarak yönetiyorsanız, Spec-First Modu denemeye değer. Güvenli bir depoda yeni bir proje oluşturun, Spec-First Modu’nu seçin ve ilk commit’i yapın. Kurulum kısa sürüyor; ekibinizin akışına uyup uymadığını görmek için birkaç gerçek değişiklik üzerinde denemek yeterli.