OpenAPI şemasını önce mi yazmalıyım yoksa koddan mı üretmeliyim?

Kısa cevap: Asıl sorununuz “spec-first mi, code-first mi” değil — drift’in kendisi. Hangi yönü seçerseniz seçin, spec ile kodu CI’da birbirine karşı doğrulamadığınız sürece ikisi yine ayrışacak. Yön bir tercih; doğrulama ise zorunluluk.

1. İki yaklaşımın gerçek farkı. Code-first’te (Scramble, L5-Swagger) şemayı controller’lardan ve annotation’lardan üretirsiniz; implementasyona sadık kalır ama tasarımı koda gömer, review’ı zorlaştırır ve annotation gürültüsü birikir. Contract-first’te önce openapi.yaml’ı yazar, kodu ona uydurursunuz; tasarımı önden konuşturur ama disiplin ister.
2. Drift’i bitiren tek şey doğrulamadır. Yön ne olursa olsun, bir contract test olmadan yayınladığınız şema ile gerçek response yine kayar. Sizin ticket’larınız tam bu boşluktan geliyor — kimse elle senkron tutmayı sürdüremez.
3. Partner’ınız varsa contract-first seçin. Sözleşmeyi önce yayınlarsınız; partner Prism gibi bir mock server ile sizi beklemeden geliştirir, siz de implementasyonu sözleşmeye kilitlersiniz. Sözleşme tartışması koda dökülmeden biter.
4. Laravel’i spec’e bağlayın. openapi.yaml’ı repo’ya koyun, PR’da Spectral ile lint edin ve Spectator ile her endpoint’in gerçek response’unu şemaya karşı doğrulayın:

$this->getJson('/api/orders/42')
    ->assertValidResponse(200); // openapi.yaml'a göre şema doğrulaması

5. Tek doğru kaynağı (SSOT) belirleyin. openapi.yaml tek gerçek olsun; yayınladığınız dokümanlar da, partner’ların ürettiği client’lar da CI’da o dosyadan türesin. İki kaynağınız varsa drift garantidir.
6. Maliyeti kabul edin. Contract-first bir öğrenme eğrisi ve YAML disiplini ister; code-first hızlı başlar ama tasarım review’ı zayıf kalır. Karar, ekibinizin sözleşmeyi elle sürdürecek olgunlukta olup olmamasıyla ilgili.

Sonuç: Ben olsam contract-first giderdim: openapi.yaml SSOT olur, PR’da Spectral lint çalışır, testlerde Spectator ile request/response doğrulanır, docs ve partner client’ları CI’da bu dosyadan üretilir. Kritik olan yön değil, o yeşil contract test — drift tespitini kod review’ın insafına değil pipeline’a yıktığınız an ticket’lar kesilir.