Apidog Spec-First Modu Nedir?

Apidog Spec-First Modu, OpenAPI spesifikasyonlarını kaynak kodu gibi yöneten ekipler için tasarlanmış beta bir çalışma alanıdır. openapi.yaml veya openapi.json dosyanızı doğrudan IDE tarzı bir düzenleyicide yazarsınız, doğrularsınız, commit edersiniz ve bağlı Git deposuyla çift yönlü senkronize edersiniz.

Apidog'u bugün deneyin

Bu kılavuzda Spec-First Modu’nu nasıl kuracağınızı, günlük iş akışında nasıl kullanacağınızı, Git senkronizasyonunu nasıl yöneteceğinizi ve beta sürümde nelere dikkat etmeniz gerektiğini adım adım göreceksiniz. Bu yaklaşımın arkasındaki daha geniş fikir için Git-yerel API iş akışı yazımıza da göz atabilirsiniz.

Apidog Spec-First Modu Nedir?

Spec-First Modu, API tasarımınızı ham bir OpenAPI belgesi olarak düzenlediğiniz Apidog beta modudur.

Bu modda tipik akış şöyledir:

1. Git deponuzu Apidog’a bağlarsınız.
2. openapi.yaml veya openapi.json dosyanızı açarsınız.
3. YAML/JSON üzerinde doğrudan değişiklik yaparsınız.
4. Değişiklikleri doğrularsınız.
5. Commit mesajı yazarak kaydedersiniz.
6. Değişiklikleri Git deposuna push edersiniz.
7. Ekip arkadaşlarınızın değişikliklerini pull ederek editörde güncellersiniz.

Spec-First Modu özellikle şu ekipler için uygundur:

• OpenAPI sözleşmelerini Git’te versiyonlayan backend ekipleri
• API değişikliklerini pull request üzerinden inceleyen platform ekipleri
• openapi.yaml dosyasını tek doğruluk kaynağı olarak kullanan API-first şirketler
• Görsel form yerine doğrudan YAML/JSON düzenlemeyi tercih eden geliştiriciler

Bu yaklaşımda spesifikasyon dosyası projenin kendisidir. Git ise geçmişi, dallanmayı, incelemeyi ve ekip iş birliğini yönetir.

Spec-First Modu ve Design-First Modu: Farklar

Apidog iki farklı çalışma modu sunar:

• Design-First Modu: Görsel ve form tabanlı API tasarım deneyimi.
• Spec-First Modu: Ham OpenAPI YAML/JSON düzenleme ve Git senkronizasyonu.

Detaylı karşılaştırma için spec-first vs design-first karşılaştırması yazısını okuyabilirsiniz.

Yön	Design-First Modu	Spec-First Modu (Beta)
Birincil düzenleyici	Görsel formlar ve kullanıcı arayüzü panelleri	Ham YAML/JSON kod düzenleyici
Doğruluk kaynağı	Apidog proje veritabanı	Git deponuzdaki spesifikasyon dosyası
Git senkronizasyonu	Dışa aktarma/içe aktarma tabanlı	Yerel çift yönlü senkronizasyon
En uygun olduğu durumlar	Görsel tasarımcılar, karma ekipler	Git’e yerel mühendislik ekipleri
Öğrenme eğrisi	Daha rehberli	OpenAPI biliyorsanız tanıdık

Hiçbir mod mutlak olarak daha iyi değildir. Seçim, ekibinizin API sözleşmelerini nasıl yönettiğine bağlıdır.

Temel Özellikler

Spec-First Modu yalnızca bir metin editörü değildir. OpenAPI düzenleyici, gezilebilir taslak, Git entegrasyonu, değişiklik takibi ve ekip izinlerini aynı akışta birleştirir.

1. IDE Tarzı OpenAPI Düzenleyici

Spec-First çalışma alanının merkezinde YAML/JSON düzenleyebileceğiniz bir kod editörü bulunur.

Editör şunları destekler:

• YAML ve JSON düzenleme
• OpenAPI/Swagger sözdizimi vurgulama
• Şema doğrulama
• Otomatik tamamlama
• Hatalı alanları veya eksik zorunlu değerleri yazarken yakalama

Örneğin aşağıdaki gibi bir endpoint tanımı üzerinde doğrudan çalışabilirsiniz:

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'

Bu yaklaşım özellikle büyük OpenAPI dosyalarında faydalıdır. Örneğin additionalProperties, $ref, required, enum veya oneOf gibi alanları elle yazarken doğrulama ve otomatik tamamlama hataları erken yakalamanıza yardımcı olur.

2. Otomatik Ayrıştırılmış Gezilebilir Taslak

Büyük bir openapi.yaml dosyasında yüzlerce endpoint, şema ve bileşen olabilir. Spec-First Modu dosyanızı otomatik ayrıştırır ve sol tarafta gezilebilir bir taslak oluşturur.

Bu taslakta genellikle şu yapılar görünür:

• Paths
• Operations
• Schemas
• Components

Bir düğüme tıkladığınızda editör doğrudan ilgili YAML/JSON bölümüne gider. Böylece “1847. satıra gitmek” yerine “POST /orders operasyonuna gitmek” şeklinde çalışırsınız.

Bu özellikle şu durumlarda işinizi hızlandırır:

• Büyük API sözleşmelerinde endpoint bulma
• Şema tanımlarına hızlı geçiş
• $ref ile bağlı bileşenleri düzenleme
• Dosya içinde manuel arama ihtiyacını azaltma

3. Çift Yönlü Git Senkronizasyonu

Spec-First Modu’nun ana farkı Git ile çift yönlü çalışmasıdır.

Desteklenen bağlantı yöntemleri:

Sağlayıcı	Nasıl bağlanır
GitHub	Doğrudan entegrasyon
GitLab	Doğrudan entegrasyon
Azure DevOps	Genel Git Bağlantısı aracılığıyla

GitHub veya GitLab kullanıyorsanız doğrudan yetkilendirme yapabilirsiniz. Azure DevOps için Apidog’u standart Git kimlik bilgileriyle deponuza bağlarsınız.

Akış basittir:

Git deposu -> pull -> Apidog editörü
Apidog editörü -> commit -> push -> Git deposu

Belirli bir sağlayıcıya odaklanmak isterseniz OpenAPI spesifikasyonunu GitHub’a senkronize etme kılavuzu bu akışı adım adım açıklar.

4. Commit, Push ve Senkronizasyon Durumu

Spec-First Modu’nda değişiklikleri yalnızca kaydedip bırakmazsınız. Git’e benzer bir akış izlersiniz:

1. Dosyada değişiklik yaparsınız.
2. Değişiklikleri gözden geçirirsiniz.
3. Commit mesajı yazarsınız.
4. Commit edersiniz.
5. Push edersiniz.
6. Senkronizasyon durumunu kontrol edersiniz.

Senkronizasyon göstergesi, yerel spesifikasyonunuzun Git deposuyla uyumlu olup olmadığını gösterir. Örneğin “Şimdi senkronize edildi” durumu, editördeki spesifikasyon ile bağlı dalın eşleştiğini belirtir.

Bu, özellikle ekip halinde çalışırken önemlidir. Hangi değişikliğin yerel kaldığını, hangisinin depoya gönderildiğini net biçimde görebilirsiniz.

5. Dosya Değişikliği Takibi

Commit etmeden önce Spec-First Modu değişiklikleri dosya düzeyinde gösterir.

Değişiklikler şu şekilde işaretlenir:

• Değiştirilmiş
• Eklenmiş
• Silinmiş

Bu adım, commit öncesi kontrol noktası gibi çalışır. Örneğin yalnızca yeni bir endpoint eklemek istediyseniz ama yanlışlıkla başka bir şemayı değiştirdiyseniz, bunu push etmeden önce görebilirsiniz.

Gönderilmemiş değişiklikleri istemiyorsanız push etmeden önce atabilirsiniz. Böylece deneysel veya hatalı düzenlemeler Git geçmişine girmez.

6. Depo, Dal ve Ekip İzinleri

Bir Spec-First projesi belirli bir Git deposuna ve belirli bir dala bağlıdır. Genellikle bu dal main olur, ancak ekibinizin akışına göre farklı bir dal da seçebilirsiniz.

Kurulum sırasında ayrıca ekip izinlerini yapılandırırsınız:

• Kim projeye erişebilir?
• Kim spesifikasyonu düzenleyebilir?
• Kim değişiklikleri yönetebilir?

Bu yapı, API sözleşmesini Git’teki gerçek proje yapınızla hizalı tutar.

Spec-First Modu Nasıl Kurulur?

Kurulum doğrusal bir akıştır. Ekran görüntülü resmi rehber için docs.apidog.com/spec-first-mode-beta-2058268m0 adresine bakabilirsiniz.

Adım 1: API’ler Modülünde Modu Değiştirin

Apidog’da API’ler modülünü açın. Sol alt taraftaki mod düğmesini bulun ve Design-First yerine Spec-First Modu’nu seçin.

Adım 2: Git Sağlayıcınızı Bağlayın

Kullandığınız Git sağlayıcısına göre bağlantıyı yapılandırın:

• GitHub için doğrudan entegrasyonu kullanın.
• GitLab için doğrudan entegrasyonu kullanın.
• Azure DevOps için genel Git Bağlantısı kurun.

Adım 3: Depodan Proje Oluşturun

Spesifikasyon dosyanızın bulunduğu depoyu seçin. Ardından çalışmak istediğiniz dalı belirleyin.

Örnek yapı:

repo/
  api/
    openapi.yaml
  src/
  README.md

Bu durumda Apidog’daki Spec-First projesi Git’teki gerçek openapi.yaml dosyasına bağlı olur.

Adım 4: Ekip İzinlerini Tanımlayın

Kurulum sırasında projeye erişecek ekip üyelerini ve izinlerini belirleyin. API sözleşmesini yalnızca ilgili kişilerin değiştirebilmesi için izinleri net tutun.

Adım 5: OpenAPI Dosyasını Düzenleyin

openapi.yaml veya openapi.json dosyanızı açın. Sol taraftaki taslak üzerinden endpoint veya şemalara gidin.

Örnek düzenleme:

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]

Adım 6: Değişiklikleri Gözden Geçirin

Commit etmeden önce dosya değişikliklerini kontrol edin. Beklemediğiniz bir değişiklik varsa atın.

Adım 7: Commit Edin

Açık ve anlaşılır bir commit mesajı yazın.

Örnek commit mesajları:

Add POST /invoices endpoint
Update User schema required fields
Fix response schema ref for GET /orders

Adım 8: Push Edin ve Senkronizasyonu Kontrol Edin

Commit sonrası değişikliği bağlı dala push edin. Senkronizasyon göstergesi “Şimdi senkronize edildi” durumuna geldiğinde editördeki spesifikasyon ile Git deposu eşleşmiş olur.

Özet akış:

Modu değiştir
  -> Git deposunu bağla
  -> Proje oluştur
  -> YAML/JSON düzenle
  -> Değişiklikleri kontrol et
  -> Commit et
  -> Push et
  -> Senkronizasyonu doğrula

Günlük Kullanım Akışı

Spec-First Modu kurulduktan sonra günlük çalışma akışı Git tabanlıdır.

Tipik bir gün şöyle ilerler:

1. Güne bağlı daldan son değişiklikleri pull ederek başlarsınız.
2. Sol taslaktan üzerinde çalışacağınız endpoint’i seçersiniz.
3. YAML veya JSON üzerinde değişiklik yaparsınız.
4. Editör doğrulama ve otomatik tamamlama ile hataları erken gösterir.
5. Değişiklik takibini kontrol edersiniz.
6. Commit mesajı yazarsınız.
7. Commit ve push yaparsınız.
8. Ekip arkadaşınız değişikliği Git üzerindeki normal inceleme sürecinde değerlendirir.

Örneğin yeni bir fatura şeması ekliyorsanız şu yapıyı tanımlayabilirsiniz:

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]

Ardından bunu bir endpoint yanıtında kullanabilirsiniz:

paths:
  /invoices/{invoiceId}:
    get:
      summary: Get invoice by ID
      operationId: getInvoiceById
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Invoice detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'

Bu akışta API sözleşmesi kod gibi davranır: düzenlenir, doğrulanır, commit edilir, incelenir ve versiyonlanır.

Spec-First Modu Kimler İçin Uygun?

Spec-First Modu özellikle Git merkezli çalışan ekipler için uygundur.

Bu modu tercih edin, eğer:

• API sözleşmelerini Git deposunda tutuyorsanız
• OpenAPI dosyasını pull request ile inceliyorsanız
• Backend veya platform ekibiniz YAML/JSON düzenlemeye alışkınsa
• API spesifikasyonunun servis koduyla birlikte versiyonlanmasını istiyorsanız
• Form tabanlı arayüz yerine doğrudan spesifikasyon dosyasıyla çalışmak istiyorsanız

Design-First Modu daha uygun olabilir, eğer:

• Ekibiniz görsel API tasarımı tercih ediyorsa
• Ürün, tasarım veya teknik olmayan ekipler API tasarımına katkı veriyorsa
• YAML yazmak yerine form tabanlı düzenleme istiyorsanız
• Daha rehberli bir düzenleme deneyimi arıyorsanız

Karar verirken ekibinizin gerçekte nasıl çalıştığına bakın. Daha ayrıntılı değerlendirme için karşılaştırma yazısı faydalı olacaktır.

Beta Sürümde Dikkat Edilmesi Gerekenler

Spec-First Modu beta bir özelliktir. Bu nedenle üretim iş akışınıza almadan önce dikkatli test etmeniz gerekir.

Dikkat edilmesi gerekenler:

• Özellikler ve davranışlar beta sürecinde değişebilir.
• GitHub ve GitLab doğrudan desteklenir.
• Azure DevOps genel Git Bağlantısı üzerinden çalışır.
• Kritik bir API sözleşmesini taşımadan önce küçük veya kritik olmayan bir depoda deneyin.
• Commit ve push adımlarını bilinçli yapın.
• Gönderilmemiş değişiklikleri push etmeden önce mutlaka inceleyin.
• Gerekirse istenmeyen yerel değişiklikleri discard edin.

Pratik öneri:

Önce test deposu
  -> Küçük bir OpenAPI dosyası
  -> Basit edit-commit-push döngüsü
  -> Ekip içi deneme
  -> Güven oluşunca gerçek projeye geçiş

Beta sürecinin avantajı, geri bildirimlerin ürün yönünü etkileyebilmesidir. İş akışınızda eksik kalan bir nokta varsa raporlamak değerlidir.

SSS

Spec-First Modu ücretsiz mi?

Spec-First Modu, Apidog içinde beta bir özelliktir. Erişiminiz Apidog planınıza ve beta kullanılabilirliğine bağlıdır. En doğrudan yol, API’ler modülünde modu etkinleştirip hesabınızda kullanılabilir olup olmadığını kontrol etmektir.

Hangi Git sağlayıcıları destekleniyor?

GitHub ve GitLab doğrudan entegrasyonla desteklenir. Azure DevOps genel Git Bağlantısı aracılığıyla kullanılabilir. Diğer Git sunucuları da standart Git bağlantısı üzerinden çalışabilir.

Design-First Modu’na geri dönebilir miyim?

Evet. API’ler modülünün sol altındaki mod düğmesinden Spec-First ve Design-First arasında geçiş yapabilirsiniz. Tek bir moda kilitlenmezsiniz.

Hangi dosya formatlarını düzenleyebilirim?

OpenAPI belgenizi YAML veya JSON olarak düzenleyebilirsiniz. Editör OpenAPI ve Swagger için sözdizimi vurgulama, şema doğrulama ve otomatik tamamlama sağlar.

Gönderilmemiş değişikliklerime ne olur?

Gönderilmemiş değişiklikler push edene kadar yerel kalır. Spec-First Modu değişiklikleri değiştirilmiş, eklenmiş veya silinmiş olarak izler. Bir değişiklikten vazgeçerseniz push etmeden önce atabilirsiniz.

Sonuç

Apidog Spec-First Modu, OpenAPI düzenleme ve Git senkronizasyonunu aynı çalışma alanında birleştirir. YAML veya JSON dosyanızı doğrudan düzenler, taslak üzerinden gezinir, yazarken doğrular, commit eder ve GitHub, GitLab veya Azure DevOps ile çift yönlü senkronize edersiniz.

Bu mod özellikle API sözleşmesini kaynak kodu gibi yöneten Git-yerel ekipler için uygundur. Başlamak için API’ler modülünde Spec-First Modu’nu etkinleştirin, bir depo bağlayın ve küçük bir edit-commit-push döngüsü deneyin. Hazır olduğunuzda belgelerde Spec-First Modu’nu deneyin.