Swagger’dan RTK Query’ye: Tek Komutla API Üretimi
Modern web ve mobil uygulamalarda API katmanı, sistem mimarisinin en kritik bileşenlerinden biridir. Özellikle domain sayısının ve entegrasyon noktalarının arttığı uygulamalarda API yönetimi yalnızca veri alışverişi problemi olmaktan çıkar, ekipler arası senkronizasyon, tip güvenliği, sürüm yönetimi, önceki versiyonlarla uyumluluk, bakım maliyeti gibi konuları da doğrudan etkileyen bir mimari probleme dönüşür. Endpoint sayısı arttıkça elle kod yazımı yavaşlar ve hata riski büyür. Bu nedenle, Swagger tanımının tek kaynak kabul edilip API dosyalarının otomatik üretilmesi günlük geliştirme hayatını gözle görülür sekilde kolaylaştırır.
Bu yazıda, “Swagger değişti -> API katmanı güncellendi” sürecini tek komuta indirip tekrar edilebilir hale getirmek amacıyla kullanılabilecek `api-generate` komutunun ne kazandırdığı, nasıl tanımlandığı, arkasındaki akışın nasıl olduğu ve hangi dosyaların bu süreçte rol aldığı ele alınacaktır.
Avantajları
`api-generate` benzeri bir akış sayesinde:
1. Swagger değiştikten sonra API katmanı dakikalar içinde güncellenir.
2. Elle endpoint yazımından kaynaklanan tutarsızlıklar azalır.
3. Endpointler kategorilere ayrıldığı için kod tabanı daha okunabilir kalır.
4. RTK Query hook’lari otomatik oluştuğu için ekran geliştirme süreçleri hızlanır.
Özetle, bu tip komut ile altyapı operasyonlarına harcanan zaman ve hata oranı azaltılıp ürün geliştirmeye daha fazla odaklanılabilir.
Tek Komut, Üç Adımlı Süreç
1) Config’i Swagger’dan Üretmek
Bu adımın merkezinde `scripts/update-openapi-config.mjs` bulunur.
Script once `yarn pre-codegen` çalıştırır, sonra `json` dosyası okunup `paths` altından kategori bilgisi çıkarır. Ardından `openapi-config.js` içindeki `outputFiles` blogu otomatik olarak yeniden oluşturulur.
Böylece kategori eşlemelerinin tek tek elle yazılması gerekmez. Swagger’da ne varsa config onunla uyumlu şekilde şekillenir.
Örnek bir path düşünelim:
`/api/Account/GetAccounts`
Bu path’ten kategori `/api/Account` olarak çıkarılır ve hedef dosya şu şekilde üretilir:
`./src/apis/common/accountApi.ts`
Buradaki config’in manuel bakım maliyeti ciddi şekilde düşürülür.
2) Pre-Codegen Neden Var?
`scripts/pre-codegen.sh`, codegen öncesi veri temizliği yapıyor.
Bu script’in amacı Swagger içindeki enum alanlarda yer alan negatif değerleri temizlemektir. Çünku bu tür veriler codegen aşamasında tip üretimini bozabilir veya tutarsız sonuç üretebilir.
Çalışma mantığı:
1. Sistemde `jq` varsa JSON temizliği doğrudan `jq` ile yapılır.
2. `jq` yoksa fallback olarak `node precodegen.js` devreye girer.
Bu sayede farkli geliştirici ortamları arasında davranış tutarlılığı korunur.
3) openapi-config.js’in Stratejik Rolü
`openapi-config.js`, codegen’in beyni gibi davranır. Burada:
1. Swagger kaynağı (`schemaFile`) tanımlanır.
2. Base RTK Query API dosyası (`apiFile`) belirtilir.
3. Import edilecek API nesnesi (`apiImport`) seçilir.
4. Hook üretimi (`hooks: true`) aktif edilir.
5. Endpointlerin hangi dosyaya gideceği (`outputFiles`) belirlenir.
Get Selcen Haskırış Canbay’s stories in your inbox
Join Medium for free to get updates from this writer.
`pathMatcher` fonksiyonu burada kilit rol oynar. Endpoint path’i regex ile eşleştirilir ve ilgili kategori dosyasına yazılır.
Örneğin;
- Regex: `/\/api\/Account\//i`
- Çıkış dosyası: `./src/apis/common/accountApi.ts`
Bu tasarım sayesinde API katmanı tek ve büyük bir dosya yerine domain bazlı parçalara ayrılır.
4) Asıl Üretim Aşaması: RTK Query Codegen
Sıradaki komut:
npx @rtk-query/codegen-openapi openapi-config.js
Bu adımda codegen:
1. Swagger spec’i parse eder.
2. `outputFiles` kurallarına göre endpointleri böler.
3. Her kategori için ilgili `*Api.ts` dosyasını oluşturur veya günceller.
4. Kullanım için RTK Query hook’larını üretir.
Sonuç: UI tarafında doğrudan kullanılabilecek, daha tutarlı bir API katmanı.
Gerçek Hayat Senaryosu: Yeni Bir Kategori Eklendi
Swagger tarafına yeni bir grup geldiği düşünülebilir: `/api/Campaign/…`
Bu durumda yapılması gereken sadece aşağıdaki komutu çalıştırmaktır:
yarn api-generate
Kalan adımlar sistem tarafından aşağıdaki şekilde tamamlanır:
1. Yeni kategori tespit edilir.
2. `openapi-config.js` güncellenir.
3. `campaignApi.ts` benzeri yeni dosyalar üretilir.
Bu otomasyon, özellikle büyük ekiplerde API değişikliklerinin ürüne yansıma süresini hissedilir biçimde kısaltır.
Karşılaşılan Sorunlar, Edinilen Deneyimler
1. `jq is not installed` mesajı alınabilir.
Bu bir hata degildir. Script fallback ile devam eder.
2. Yeni endpoint dosyası oluşmadıysa path yapısının kontrol edilmesi gerekir.
Kategori çıkarımı `/api/<Category>/…` desenine gore yapılıyor.
3. Lint problemi görüldüyse post adımının çalıştığı doğrulanmalıdır.
`postCodegen.sh` bu konuda kritik.
4. Eski endpointler görünüyorsa Swagger dosyasının güncelliği kontrol edilmelidir.
Kaynak eskiyse çıktı da eski olur.
Sonuç
Bu yapı sadece teknik bir codegen otomasyonu degil; geliştirme süreci için bir hız çarpanı olarak değerlendirilebilir. Swagger değişikliği alıp RTK Query katmanına tutarlı, izlenebilir ve tekrar edilebilir şekilde taşınmış olur.
API katmanında “elle müdahale” hala büyük yer tutuyorsa, bu tür bir akış kurmak geliştirme hızına ve kalite istikrarına doğrudan etki eder.
