OpenAPI

OpenAPI Spesifikasyonu, bir HTTP API’sini yalnızca insanların değil araçların da okuyabileceği biçimde tarif etmek için standart bir formattır. Tek bir belge her yolu ve metodu, her birinin aldığı parametreleri, JSON Schema olarak istek ve yanıt gövdelerini, durum kodlarını ve kimlik doğrulama şemalarını listeler. Swagger ilk adıydı; güncel ana sürüm OpenAPI 3.1’dir.

Nasıl çalışır

Tek bir belgeden araçlar etkileşimli referans dokümantasyonu, birçok dilde istemci SDK’ları, sunucu iskeletleri, mock sunucular ve sözleşme testleri üretir. Aynı dosya CI’da çalışan API’ye karşı kontrol edilebilir; böylece tarif ile uygulama, bir build kırılmadan birbirinden kopamaz.

Yaygın yanılgı

Bir OpenAPI dosyasının API’nin anlatıldığı gibi davrandığını kanıtladığı sanılır. O bir test değil bir iddiadır: bir işleyicinin spesifikasyonun hiç bahsetmediği bir alanı ya da listelemediği bir durumu döndürmesini hiçbir şey engellemez. Değeri gerçek yanıtlara karşı kontrol edilmesinden gelir; sözleşme testi tam olarak bunu yapar.

Burada deneyin

Buradaki her API kendi OpenAPI 3.1 belgesini /docs/{api-id}/openapi.json adresinde yayımlar; /openapi.json ise tüm kataloğu kapsar. İkisi de dokümantasyon sayfalarının çizdiği tanımlardan üretilir.

İlgili

Kaynaklar

OpenAPI 3.1 specification

Diğer terimler

Sözleşme testi (sözleşme testi) — Bir API ile tüketicilerinin, birlikte çalıştırılmadan, istek ve yanıtların biçiminde anlaştığını test etmek.
JSON Şeması — Geçerli bir JSON belgesinin nasıl göründüğünü anlatan, böylece belgelerin otomatik doğrulanabildiği bir JSON sözlüğü.
REST API — Bir sistemi adreslenebilir kaynaklar olarak modelleyen ve onları standart HTTP metotlarıyla değiştiren API.
API uç noktası (endpoint) — Bir URL ile bir HTTP metodunun birleşimi — bir istemcinin çağırabileceği en küçük API birimi.
Sorgu parametreleri — URL’deki ? işaretinden sonra gelen, bir uç noktanın döndürdüğünü filtrelemek, sıralamak ya da sayfalamak için kullanılan anahtar=değer çiftleri.
Yollar — Bir URL yolunun, /orders/42’deki 42 gibi, belirli bir kaynağı tanımlayan değişken parçası.

Bu sayfayı İngilizce okuyun

Tüm sözlük maddeleri · Test teknikleri · 39 mock REST API’nin tamamı

Son güncelleme 16 Ekim 2026