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

> Asıl sorun spec değil, drift. İster contract-first gidin ister koddan üretin; drift'i bitiren tek şey CI'da spec'i koda karşı doğrulamak ve tek doğru kaynak yapmaktır.

- Soruldu: 2026-08-10
- Yanıtlandı: 2026-08-14
- Soran: Ece
- Etiketler: api, openapi, contract-first
- Kaynak: https://www.muhammetsafak.com.tr/sor-bakalim/openapi-semasini-once-mi-yazmaliyim-yoksa-koddan-mi-uretmeliyim/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
**Soru:** Laravel 11 ile bir REST API geliştiriyorum ve dokümantasyonu ayrı bir OpenAPI dosyasında elle tutuyorum. Controller'larda endpoint'ler değiştikçe yayınladığım dokümanı güncellemeyi unutuyorum; kod ile şema sürekli birbirinden uzaklaşıyor.

Entegrasyon yapan partner'lar "dokümanda şu alan var ama response'ta yok" diye sürekli ticket açıyor ve bu güveni yiyor. Şemayı önce mi yazmalıyım (contract-first) yoksa koddan otomatik mi üretmeliyim (Scramble/L5-Swagger)? Hangisi drift'i gerçekten bitirir?


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:
```php
$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.