Swagger/OpenAPI ile dokümantasyon ve Scalar: API'ni kendi kendini anlatır hale getir

Güvenlik bloğunu tamamladık; API'n artık sağlam ve korunuyor. Ama bir sorun var: onu senden başka kimse nasıl kullanacağını bilmiyor. Hangi endpoint'ler var, hangi veriyi bekliyorlar, ne dönüyorlar? Bu soruların cevabını her seferinde elle anlatmak zorunda kalmak istemezsin. İşte bugün API'ni kendi kendini anlatır hale getiriyoruz: OpenAPI, Swagger ve modern bir alternatif olan Scalar ile.

Dokümantasyon Neden Bu Kadar Önemli?

Bir API yazdın ama onu kullanacak olan başkaları: frontend geliştiricin, mobil ekibin, belki başka bir şirketteki geliştiriciler. Onların senin kafandaki bilgiye erişimi yok. Hangi adrese hangi veriyi göndereceklerini, karşılığında ne alacaklarını bir yerden öğrenmeleri gerekiyor. Kötü seçenek, bunu her seferinde mesajla, e-postayla, sözle anlatmandır; hem yorucu hem de hataya açık.

İyi bir API, kendi kılavuzunu yanında taşır. Tıpkı bir cihazın kutusundan çıkan kullanım kılavuzu gibi: kullanıcı ürünü eline aldığında ne yapacağını bilmek için kimseye sormak zorunda kalmaz. API dokümantasyonu da bunu yapar; API'nin nasıl kullanılacağını, sen orada olmadan, açık ve güncel biçimde anlatır.

OpenAPI: Ortak Bir Dil

OpenAPI, bir API'nin nasıl çalıştığını tarif eden standart bir formattır. API'ndeki tüm endpoint'leri, bekledikleri veriyi ve döndükleri cevabı, makinelerin de okuyabileceği yapılandırılmış bir belgeye döker. Bu belge genelde bir JSON dosyasıdır ve API'nin eksiksiz bir haritası gibidir.

OpenAPI'nin gücü, standart olmasından gelir. Bu format üzerine kurulmuş onlarca araç var: dokümantasyon arayüzleri, test araçları, hatta senin API'ne otomatik olarak istemci kodu üreten araçlar. Sen OpenAPI belgesini bir kez ürettiğinde, bütün bu ekosistem senin API'nle konuşabilir hale gelir. Not: "OpenAPI" ile "Swagger" bazen karıştırılır; kısaca OpenAPI bir standart, Swagger ise bu standart etrafında gelişmiş araç ailesidir.

.NET 9'da OpenAPI Desteği

Güzel haber: .NET 9, OpenAPI belgesi üretmeyi kutudan çıktığı haliyle destekliyor. İkinci yazıda proje kurarken gördüğümüz o AddOpenApi ve MapOpenApi satırlarını hatırlıyor musun? İşte tam da bu işi yapıyorlardı, ama üstünde durmamıştık. Program.cs'te şu iki parça yeterli:

builder.Services.AddOpenApi();

Bu satır, OpenAPI belgesini üretecek servisi kaydeder. Sonra app tarafında belgeyi bir adres üzerinden yayınlarsın:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

Bu koşul önemli: OpenAPI belgesini genellikle yalnızca geliştirme ortamında açık tutarsın, çünkü on beşinci yazıda ortam katmanlarını konuşurken değindiğimiz gibi, canlıda API'nin iç yapısını herkese açık etmek istemeyebilirsin. Uygulamayı çalıştırıp /openapi/v1.json adresine gittiğinde, API'nin tüm haritasını içeren JSON belgesini görürsün. Bu belge senin elinle değil, kodundan otomatik üretilir; endpoint eklediğinde belge de kendiliğinden güncellenir.

Ham JSON Yetmez: İnsana Görünür Bir Arayüz

OpenAPI belgesi makineler için harika ama bir insan o ham JSON'a bakıp API'yi rahatça keşfedemez. İşte burada dokümantasyon arayüzleri devreye girer. Bunlar, OpenAPI belgesini alıp güzel, gezilebilir ve hatta interaktif bir sayfaya dönüştürür. En bilineni Swagger UI'dır.

Swagger UI, API'nin tüm endpoint'lerini bir liste halinde gösterir; her birine tıklayıp hangi parametreleri aldığını, ne döndüğünü görebilirsin. Dahası, doğrudan o sayfadan endpoint'lere istek atabilirsin; ayrı bir test aracına ihtiyaç kalmadan API'yi tarayıcıda deneyebilirsin. Bu interaktiflik, dokümantasyonu ölü bir metin olmaktan çıkarıp canlı bir oyun alanına çevirir.

Scalar: Modern Bir Alternatif

Swagger UI uzun yıllardır standart oldu ama son dönemde daha modern bir alternatif öne çıkıyor: Scalar. Scalar da aynı OpenAPI belgesini kullanır ama daha temiz, daha hızlı ve göze daha hoş gelen bir arayüz sunar. .NET topluluğunda hızla popülerleşmesinin sebebi bu: aynı işi yapar ama deneyimi daha keyiflidir.

Scalar'ı eklemek oldukça basit. Önce paketi projene katarsın:

dotnet add package Scalar.AspNetCore

Sonra app tarafında, OpenAPI belgesini yayınlayan satırın hemen yanına Scalar'ı eklersin:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

Uygulamayı çalıştırıp /scalar/v1 adresine gittiğinde, API'nin tüm endpoint'lerini modern bir arayüzde görürsün. Dikkat et: Scalar sıfırdan bir şey üretmiyor; senin zaten var olan OpenAPI belgeni alıp güzel bir yüz kazandırıyor. Yani OpenAPI temeli hazırsa, Scalar'a geçmek tek satırlık bir iştir.

Dokümantasyonu Zenginleştirmek

Otomatik üretilen dokümantasyon iyi bir başlangıç ama onu daha da faydalı kılabilirsin. Endpoint'lerinin ne işe yaradığını, parametrelerinin ne anlama geldiğini açıklamalarla zenginleştirebilirsin. Ayrıca bir endpoint'in hangi durum kodlarını dönebileceğini belirtmek, dokümantasyonu kullananın işini ciddi biçimde kolaylaştırır:

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task GetById(int id)
{
    var user = await _userService.GetByIdAsync(id);
    if (user is null)
    {
        return NotFound();
    }
    return Ok(user);
}

Buradaki [ProducesResponseType] attribute'ları, bu endpoint'in 200 veya 404 dönebileceğini dokümantasyona bildirir. Böylece API'ni kullanan biri, daha kod yazmadan hangi cevapları bekleyebileceğini görür. Beşinci yazıda durum kodlarını konuşurken öğrendiklerimiz burada dokümantasyona yansıyor; doğru durum kodu dönmek sadece işleyiş için değil, dokümantasyonun netliği için de değerli.

Küçük Bir Deneme

Projene önce AddOpenApi ve MapOpenApi'yi ekle (zaten şablonda varsa emin ol) ve /openapi/v1.json adresine giderek ham OpenAPI belgesini gör; API'nin haritasının otomatik üretildiğini fark et. Sonra Scalar paketini kurup /scalar/v1 adresini aç ve endpoint'lerini modern arayüzde gez. Bir endpoint'e doğrudan bu arayüzden istek at ve cevabı orada gör. İstersen birkaç [ProducesResponseType] ekleyip dokümantasyonun nasıl zenginleştiğini gözlemle. Bu deney, dokümantasyonun ne kadar az emekle ne kadar çok değer ürettiğini gösterir.

Bir sonraki yazıda test konusuna geçiyoruz. İlk adım unit test olacak: xUnit ve Moq ile, kodunun tek tek parçalarını izole biçimde nasıl test edeceğimizi konuşacağız. API'n artık hem güvenli hem de iyi belgelenmiş; sırada onun doğru çalıştığından emin olmanın yolu var.