OpenAPI Nedir?

OpenAPI Nedir?

OpenAPI, bir REST API’nin hangi endpoint’leri sunduğunu, hangi parametreleri beklediğini, hangi yanıtları döndürdüğünü ve nasıl yetkilendirildiğini standart bir sözleşme halinde yazar. Bu sözleşme genellikle YAML veya JSON dosyası olarak tutulur.

Swagger adı tarihsel olarak bu ekosistemle birlikte anılır: Swagger araçları OpenAPI dosyasını okuyup görsel dokümantasyon, test ekranı veya istemci kodu üretebilir. OpenAPI ise standardın adıdır.

OpenAPI Dosyasında Neler Bulunur?

• Paths: /orders/{id} gibi endpoint adresleri
• Methods: GET, POST, PUT, DELETE gibi HTTP işlemleri
• Parameters: Query, path, header ve cookie parametreleri
• Request body: Gönderilecek JSON şeması ve zorunlu alanlar
• Responses: Durum kodları, örnek yanıtlar ve hata formatları
• Security schemes: API key, OAuth2 veya bearer token tanımları

Bu dosya dokümantasyondan daha fazlasıdır. Mock sunucu, SDK üretimi, kontrat testi, gateway validasyonu ve Postman koleksiyonu üretimi için kaynak olabilir.

İş Dünyasında Kullanımı

OpenAPI, dış müşteri entegrasyonlarında, mobil uygulama arka uçlarında, ödeme ve kargo bağlantılarında ve ekipler arası servis sözleşmelerinde belirsizliği azaltır. Frontend ekibi API tamamlanmadan mock veriye karşı çalışabilir; entegrasyon yapan müşteri hangi alanın zorunlu olduğunu dokümandan görebilir.

REST API projelerinde OpenAPI dosyasının kodla birlikte versiyonlanması önemlidir. Aksi halde dokümantasyon hızla gerçek API davranışından kopar ve entegrasyon hataları artar.