Sözlük · web
OpenAPI
Tanım
OpenAPI Specification (eski adı Swagger), REST API'lerini makine-okunabilir biçimde tanımlayan açık standarttır. YAML veya JSON formatında yazılır; API endpoint'leri, parametreler, yanıt şemaları ve auth yöntemlerini belgeler. Swagger UI ile interaktif dokümantasyon otomatik üretilir.
Detaylı açıklama
OpenAPI 2016'da Swagger Specification'dan doğdu; Linux Foundation bünyesindeki OpenAPI Initiative tarafından geliştirilir. OpenAPI 3.1 güncel sürüm. API sözleşmesi ('contract') olarak kullanılır — backend ve frontend takımlar aynı spec'e göre bağımsız geliştirir.
Araçlar: Swagger UI (interaktif dokümantasyon), Swagger Editor (spec yazma), Stoplight, Redoc, Postman (otomatik import), openapi-generator (client SDK üretimi). Next.js projelerinde swagger-jsdoc + swagger-ui-react yaygın.
Neden önemli: API-first geliştirme; frontend spec'e göre mock server kurar, geliştirmeyi beklemez. 3rd party entegrasyon geliştiricileri için hazır rehber. API versiyonlama (v1, v2) spec'te yönetilir. Türkiye'de entegrasyon projesinde 'API dokümanı yok' en büyük zaman kaybı.
Kullanım senaryoları
→REST API dokümantasyonu
→API-first geliştirme sözleşmesi
→3rd party entegrasyon rehberi
→Otomatik client SDK üretimi
→API testing (Postman koleksiyonu)
Güçlü yanlar
- +Makine-okunabilir → otomatik araçlar
- +Frontend + backend bağımsız geliştirme
- +Interaktif dokümantasyon (Swagger UI)
- +SDK otomatik üretimi
Zayıf yanlar
- −Spec ve kod arasında senkronizasyon zorluğu
- −Karmaşık şemalarda bakım yükü
- −GraphQL için farklı standart (GraphQL SDL)
- −Öğrenme eğrisi (YAML/JSON spec sözdizimi)
İlgili terimler
İlgili hizmetler
OpenAPI ile ilgili proje planlıyorsan
30 dakikalık keşif görüşmesinde projene özel mimari + maliyet + ekip önerisini yazılı paylaşıyoruz.
Keşif görüşmesi başlat