OpenAPI İş Birliği Git'i Bırakmadan: Dosya Tabanlı Ekipler Nasıl Birlikte Çalışır

OpenAPI ekip işbirliği, spesifikasyon Git'e taşındığında genellikle zorlaşır. Sorun Git'in yanlış yer olması değil; tam tersine, spesifikasyon için doğru doğruluk kaynağı olmasıdır. Sorun, Git inceleme araçlarının API tasarımına katkı veren QA, ön uç ve ürün ekiplerinden çok kod inceleyen mühendisler için tasarlanmış olmasıdır.

Apidog'u bugün deneyin

Ekibiniz OpenAPI spesifikasyonlarını bir depoda YAML veya JSON olarak tutuyorsa, muhtemelen şu tabloyu görmüşsünüzdür: spesifikasyon sürüm kontrollüdür, PR ile incelenebilir durumdadır; ancak mühendis olmayan ekip üyeleri hâlâ tarayıcıda Stoplight önizlemesine bakar, sorularını Slack DM üzerinden sorar ve test etmeye başlamadan önce geliştiricilerin dosyayı güncellemesini bekler.

api-spec-as-code yaklaşımı, Git'in neden doğru bilgi kaynağı olduğunu açıklar. Bu yazı ise Git'e geçtikten sonra kalan işbirliği boşluğunu ve Apidog gibi araçların spesifikasyonu Git'ten çıkarmadan bu boşluğu nasıl kapatabileceğini gösterir.

Git'in tek başına kapatamadığı boşluk

Git; değişiklik geçmişi, dallanma ve PR diff'leri için güçlüdür. Ancak OpenAPI spesifikasyonu tüm ekip tarafından kullanılan ortak bir sözleşmeye dönüştüğünde bazı ihtiyaçlar Git'in doğal kapsamı dışında kalır.

1. Tasarım aşamasında yorum yapmak zorlaşır

Bir QA mühendisi openapi.yaml içinde tutarsız bir hata şeması gördüğünde, GitHub PR diff'inde 247. satıra yorum bırakabilir. Ancak bu deneyim, spesifikasyonu belge olarak okuyan kişiler için doğal değildir.

Daha kullanışlı akış şudur:

1. QA, belge görünümünde POST /payments uç noktasını açar.
2. Eksik idempotency-key başlığını doğrudan uç nokta üzerinde işaretler.
3. Geliştirici YAML dosyasını günceller.
4. Yorum satır numarasına değil, API öğesine bağlı kalır.

2. Ön uç ekipleri dala özel mock ister

Ön uç geliştiricileri, arka uç uygulaması tamamlanmadan önce çalışan bir mock sunucusuna ihtiyaç duyar. Git'teki ham YAML dosyası bunu tek başına sağlamaz.

Örneğin:

npx @stoplight/prism-cli mock openapi.yaml

Bu komut çalışır; ancak manuel bir adımdır. Her branch için ayrı mock URL üretmek, bunu ekip akışına bağlamak ve güncel tutmak ek bir katman gerektirir.

3. Bildirimler role göre yönlendirilmelidir

Bir ekip /payments yanıt şemasında bozucu bir değişiklik yaptığında yalnızca "dosya değişti" bildirimi yeterli değildir.

Daha faydalı bildirim şuna benzer:

/payments yanıt şeması değişti.
Etkilenen ekipler: frontend, mobile, QA
Branch: feature/payment-v2

Git webhook'ları Slack'e genel bildirim gönderebilir. Ancak uç nokta, etiket veya tüketici bazlı yönlendirme için API odaklı bir işbirliği katmanı gerekir.

4. Belge erişimi hedef kitleye göre yönetilmelidir

Genel bir GitHub deposundaki spesifikasyon herkes tarafından okunabilir. Özel depo bunu çözer; ancak harici bir iş ortağının yalnızca belirli uç noktaları görebilmesi, Git'in doğal olarak sunduğu bir yetenek değildir.

Örneğin:

• Partner: /payments, /refunds
• Dahili ekip: /admin, /internal
• QA: tüm staging uç noktaları

Bu model için belge katmanında erişim kontrolü gerekir.

İşbirliği katmanı ne yapmalı?

Pratik model şu olmalıdır:

Git = doğruluk kaynağı
İşbirliği katmanı = belge + yorum + mock + bildirim + CI/CD bağlantısı

Yani araç, OpenAPI dosyasını kendi içinde ayrı bir kopyaya dönüştürmek yerine Git'teki dosyadan okumalı ve onun üzerine ekip iş akışını bağlamalıdır.

Kategori	Örnekler	Güçlü yönler	Git'in üzerine ekledikleri
Barındırılan spesifikasyon platformları	Stoplight, SwaggerHub	Kullanıcı arayüzü, yorumlar, erişim kontrolü	Genellikle spesifikasyonun kendi kopyasını tutar; Git isteğe bağlıdır
Dosya tabanlı işbirliği katmanları	Apidog Spec-First Modu, Redocly	Git'teki dosyadan çalışır	Belge, mock, inceleme ve CI katmanı ekler
Git yerel API istemcileri	Bruno, Insomnia	Dosya senkronizasyonu, kod olarak koleksiyonlar	Genellikle istek katmanında kalır

Araç seçerken tek bir özelliğe bakmak yerine şu soruları sorun:

• Git tek doğruluk kaynağı olarak kalıyor mu?
• Yorumlar YAML satırına mı, API öğesine mi bağlı?
• Her branch için mock üretilebiliyor mu?
• CI içinde sözleşme testi çalıştırılabiliyor mu?
• Belge erişimi role göre yönetilebiliyor mu?

Bruno nerede güçlü, nerede sınırlı?

Bruno, dosya tabanlı API koleksiyonları ve Git entegrasyonu konusunda güçlüdür. Bruno Ultimate; dosya tabanlı koleksiyon depolama, Git entegrasyonu, SSO, SCIM, sır yöneticisi bağlantıları ve denetim günlüğü gibi özellikler sunar.

Eğer temel ihtiyacınız şuysa Bruno iyi bir seçenek olabilir:

Git'te duran koleksiyonları senkronize et
İstekleri çalıştır
Ortamları yönet

Ancak Bruno'nun doğal sınırı istek katmanıdır. Kaydedilmiş OpenAPI dosyasından otomatik belge üretmek, branch bazlı mock sunucuları oluşturmak veya spesifikasyon değişikliklerine göre role özel bildirim göndermek için ek araç gerekir.

Bu nedenle, zaten Stoplight ile belge ve mock yönetiyorsanız Bruno'yu eklemek Stoplight'ın yerini almak değil, yanına yeni bir araç eklemek anlamına gelir.

Apidog Spec-First Modu nasıl çalışır?

Apidog'un Spec-First Modu şu mimari için tasarlanmıştır:

openapi.yaml Git'te kalır
Apidog dosyayı okur
Belge, yorum, mock, test ve bildirim katmanı eklenir

Apidog burada spesifikasyonu kendi veritabanına çatallayan ana kaynak gibi davranmaz. Yetkili kaynak Git'teki dosyadır.

Uygulama adımları

Adım 1: Git deponuzu bağlayın

Apidog'da bir projeyi GitHub, GitLab veya Bitbucket deposuna bağlayın ve OpenAPI dosya yolunu belirtin.

Örnek depo yapısı:

repo/
  api/
    openapi.yaml
  src/
  .github/
    workflows/

Örnek OpenAPI dosyası:

# api/openapi.yaml
openapi: "3.1.0"
info:
  title: Payments API
  version: "2.4.0"

paths:
  /payments:
    post:
      summary: Create a payment
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentRequest"
      responses:
        "201":
          description: Payment created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentResponse"
        "422":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"

components:
  schemas:
    PaymentRequest:
      type: object
      required: [amount, currency, source]
      properties:
        amount:
          type: integer
          description: Amount in smallest currency unit, for example cents
        currency:
          type: string
          enum: [usd, eur, gbp]
        source:
          type: string
          description: Payment method token

    PaymentResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, completed, failed]

    ValidationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

Bağlantı adımları için apidog-git-integration-sync rehberine bakabilirsiniz.

Adım 2: Diff yerine API öğesi üzerinden inceleme yapın

Depo bağlandıktan sonra Apidog, OpenAPI dosyasını etkileşimli belge olarak gösterir. Ekip üyeleri doğrudan şunlara yorum bırakabilir:

• Uç noktalar
• Request body şemaları
• Response şemaları
• Örnek yanıtlar
• Header tanımları

Örneğin QA şu yorumu POST /payments üzerinde açabilir:

Bu uç nokta için idempotency-key header'ı zorunlu olmalı mı?
Tekrarlı ödeme riskini nasıl engelliyoruz?

Geliştirici daha sonra YAML dosyasını güncelleyip commit gönderir:

paths:
  /payments:
    post:
      parameters:
        - name: idempotency-key
          in: header
          required: true
          schema:
            type: string
          description: Prevents duplicate payment creation

Yorum, satır numarasına değil API öğesine bağlı kaldığı için değişiklik sonrası bağlam kaybolmaz.

Adım 3: Branch bazlı mock oluşturun

Spec-First Modu ile her branch, kendi OpenAPI durumuna göre ayrı mock üretebilir.

Örnek akış:

main                  -> production mock
feature/payment-v2    -> payment v2 mock
fix/validation-error  -> validation fix mock

Bu, ön uç geliştirme için özellikle kullanışlıdır:

1. Backend ekibi feature/payment-v2 branch'inde OpenAPI şemasını günceller.
2. Apidog bu branch'e bağlı mock üretir.
3. Frontend ekibi yeni mock URL ile entegrasyona başlar.
4. Backend tamamlanmadan UI geliştirme ilerler.

Adım 4: Bildirimleri doğru ekibe gönderin

Spesifikasyonda bir yol veya şema değiştiğinde bildirimleri uç nokta, etiket veya yol ön ekine göre yönlendirmek daha kullanışlıdır.

Örnek yönlendirme modeli:

/payments/**  -> #payments-frontend, #mobile
/admin/**     -> #internal-backend
/refunds/**   -> #finance-qa

Slack için Slack gelen webhook'ları, Teams için Microsoft Teams gelen webhook'ları belgelerine bakabilirsiniz.

Deneme sırasında özellikle şunları doğrulayın:

• Bildirimler etiket bazında mı, yol bazında mı yönlendirilebiliyor?
• Bozucu değişiklikler ayrı işaretlenebiliyor mu?
• Belge hedef kitleleri kuruluş rollerinizle eşleşiyor mu?

CI/CD ile sözleşme testi ekleyin

İşbirliği katmanı yalnızca belge ve yorum için değil, CI/CD için de kullanılmalıdır.

Temel hedef:

OpenAPI dosyası geçerli mi?
API uygulaması bu sözleşmeye uyuyor mu?
Değişiklikler PR sırasında yakalanıyor mu?

Bunun için linting ve sözleşme testini aynı pipeline içinde çalıştırabilirsiniz.

# .github/workflows/api-spec.yml
name: API spec validation and test

on: [push, pull_request]

jobs:
  validate-and-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI spec with Spectral
        run: |
          npm install -g @stoplight/spectral-cli
          spectral lint api/openapi.yaml --ruleset .spectral.yaml

      - name: Run Apidog contract tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          npx apidog-cli run \
            --project-id ${{ vars.APIDOG_PROJECT_ID }} \
            --test-suite "Payments API smoke" \
            --environment staging

OpenAPI spesifikasyonu, API'nizin ne vaat ettiğini tanımlar. CI içinde sözleşme testi çalıştırmak, yalnızca birim testleri değil, çalışan servisin bu sözleşmeden sapıp sapmadığını da kontrol eder.

Linting için Spectral veya Redocly CLI kullanabilirsiniz. Git-yerel uçtan uca akış için git-native-api-workflow yazısına bakabilirsiniz.

Dosya tabanlı ekipler için karşılaştırma

Aşağıdaki tablo, OpenAPI dosyasını Git'te tutmak isteyen ekipler için temel değerlendirme başlıklarını özetler. Soru işaretiyle belirtilen yetenekleri kendi denemenizde doğrulamanız gerekir; plan ve yapılandırmaya göre değişebilir.

Yetenek	Stoplight	SwaggerHub	Apidog Spec-First, beta
Git'in yetkili kaynak olması	İsteğe bağlı; varsayılan olarak kendi kopyası	İsteğe bağlı	Evet
Tasarım aşaması yorumları	Evet	Evet	Evet
Branch bazlı mock	Evet	Kısmi	Evet
Role dayalı belge erişimi	Evet	Evet	Denemede kontrol edin
Projeler arası şema yeniden kullanımı	Evet	Evet	Denemede kontrol edin
CI/CD sözleşme testi	Prism aracılığıyla	Sınırlı	Evet, Apidog CLI ile
Özel lint kuralları	Spectral aracılığıyla	Sınırlı	Denemede kontrol edin
SSO/SCIM	Ücretli katmanlar	Kurumsal	Denemede kontrol edin
Bildirim yönlendirme	Webhook'lar aracılığıyla	Sınırlı	Evet
Çift kopya olmadan dosya tabanlı çalışma	Hayır	Hayır	Evet, Spec-First ile

SwaggerHub karşılaştırması için swaggerhub-vs-apidog-collaboration yazısına bakabilirsiniz.

Sıkça sorulan sorular

Git PR incelemelerini Apidog yorumlarıyla birlikte kullanabilir miyiz?

Evet. İki akış farklı kitlelere hizmet eder.

• Git PR incelemeleri: YAML değişikliğini inceleyen mühendisler
• Apidog yorumları: spesifikasyonu belge olarak inceleyen QA, ürün ve ön uç ekipleri

Kaydedilmiş OpenAPI dosyası her iki akış için de tek doğruluk kaynağı olarak kalır.

Biri spesifikasyonu Apidog arayüzünde düzenlerse ne olur?

Spec-First Modu'nda Apidog arayüzündeki düzenlemeler Git'e commit olarak gönderilebilir. Tipik akış şöyledir:

UI'da düzenle
Branch'e commit et
Git'te PR aç
PR incelemesini tamamla
Merge et

Bu akışı kendi denemenizde doğrulamanız önemlidir. Özellikle düzenlemelerin nereden başlayacağına karar vermelisiniz:

• Yalnızca Git'ten Apidog'a mı?
• Apidog'dan Git'e commit de olacak mı?
• PR zorunlu mu?

Adım adım inceleme için spec-first-mode-apidog-beta-walkthrough yazısına bakabilirsiniz.

Spec-First Modu monorepo içinde çalışır mı?

Birden fazla OpenAPI dosyası olan monorepo yapıları yaygındır.

Örnek:

repo/
  services/
    payments/
      openapi.yaml
    identity/
      openapi.yaml
    notifications/
      openapi.yaml

Apidog, farklı dosya yollarına bağlı birden fazla projeyi destekler. Ancak tek bir Apidog projesinin birden fazla OpenAPI dosyasına eşlenip eşlenemeyeceğini veya lint kurallarının projeler arasında nasıl paylaşılacağını kendi depo yapınızla test etmeniz gerekir.

Redocly ile nasıl karşılaştırılır?

Redocly CLI, OpenAPI linting, bundling ve dosyalardan belge üretme konusunda güçlüdür. Redocly'nin barındırılan platformu ekip özellikleri ve inceleme katmanı ekler.

Fark şudur:

• Redocly CLI, dosya tabanlı otomasyon için güçlüdür.
• Redocly platformu, işbirliği özelliklerini barındırılan katmanda sunar.
• Apidog, Git'teki dosyadan okuyan tek bir platformda belge, mock, sözleşme testi ve bildirimleri birleştirmeyi hedefler.

OpenAPI Girişimi'nin araçları bu problemi çözer mi?

OpenAPI Girişimi, spesifikasyonun kendisini yayınlar; işbirliği platformu yayınlamaz. Seçtiğiniz araç, OpenAPI spesifikasyonunu uygulayan ekosistemin parçasıdır.

Eğer OpenAPI 3.1 kullanıyorsanız, seçtiğiniz aracı mutlaka OpenAPI 3.1 desteği açısından test edin. 3.1 desteği araçlar arasında farklılık gösterebilir.

Sonuç

OpenAPI dosyanız Git'teyse sürümleme problemi büyük ölçüde çözülmüştür. Ancak ekip işbirliği problemi hâlâ devam eder.

Pratikte ihtiyacınız olan katman şunları sağlamalıdır:

• Mühendis olmayan ekipler için API öğesi bazlı yorumlar
• Ön uç ekipleri için branch bazlı mock'lar
• Bozucu değişiklikler için role özel bildirimler
• Hedef kitleye göre erişim kontrollü belgeler
• CI/CD içinde linting ve sözleşme testi

Bu katmanın Git'in yerini alması gerekmez. Git'ten okumalı, onun üzerine inşa edilmeli ve mühendislerin PR tabanlı kod inceleme akışını bozmamalıdır.

Mevcut kurulumunuzda Git sürümlemeyi, Stoplight veya benzeri bir araç belge işbirliğini sağlıyorsa, Apidog Spec-First Modu bu iki tarafı birleştirmek için tasarlanmıştır. Beta aşamasında olduğu için özellikle belge erişim kontrolü, şema yeniden kullanımı ve bildirim ayrıntı düzeyi gibi ihtiyaçları kendi ekibinizin akışıyla test edin.

Apidog'u indirin ve mevcut OpenAPI deponuzun bir branch'ine bağlayarak işbirliği katmanının Git tabanlı akışınıza nasıl uyduğunu deneyin.