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

> `openapi.yaml`'ı tek doğru kaynak yapıp contract-first gidin; drift'i bitiren şey yön değil, CI'da spec'i koda karşı doğrulayan yeşil contract testtir.

- Soruldu: 2026-08-10
- Yanıtlandı: 2026-08-14
- Soran: Ece
- Etiketler: api, api-design
- Kaynak: https://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.

## Kısa cevap

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. Sözleşmeyi önden yazmanın tasarım tarafını [contract-first yazısında](/tr/blog/api-tasarimini-sozlesme-oncelikli-contract-first-yurutmek/) anlatmıştım; buradaki eksik parça o sözleşmeyi kodun üstünde tutan otomatik kapı.

## Neden

1. **İki yaklaşımın gerçek farkı.** Code-first'te (Scramble, L5-Swagger) şemayı controller'lardan üretirsiniz — Scramble bunu annotation yazmaya gerek kalmadan otomatik yapar, L5-Swagger ise annotation'lara dayanır; 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`'ı yazarsınız, 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. **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.

## Ne yapmalı

1. **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.

2. **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ı
   ```

3. **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.

**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.

## İlgili Yazılar

- [API'leri OpenAPI ile belgelemek](/tr/blog/apileri-openapi-ile-belgelemek/) — Blog
- [API tasarımını sözleşme öncelikli (contract-first) yürütmek](/tr/blog/api-tasarimini-sozlesme-oncelikli-contract-first-yurutmek/) — Blog
- [API hata gövdelerimi RFC 7807 problem+json biçimine mi taşımalıyım?](https://muhammetsafak.com/tr/sor-bakalim/api-hata-govdelerimi-rfc-7807-problem-json-tasimaliyim/) — Sor Bakalım
- [Public API'mde bir endpoint'i kullanımdan kaldırırken sunset sürecini nasıl yönetmeliyim?](https://muhammetsafak.com/tr/sor-bakalim/public-apimde-bir-endpointi-kullanimdan-kaldirirken-sunset-surecini-nasil-yonetmeliyim/) — Sor Bakalım
- [Ödeme webhook'u aynı bildirimi tekrar gönderiyor; idempotency'i nasıl kurarım?](https://muhammetsafak.com/tr/sor-bakalim/webhook-mukerrer-bildirim-idempotency-ve-hmac/) — Sor Bakalım