API Dokümantasyonunda Swagger Dönemi Bitiyor: Scalar ile Modern ve İnteraktif API Arayüzleri

0:00

/0

1×

API Dokümantasyonunda Swagger Dönemi Bitiyor: Scalar ile Modern ve İnteraktif API Arayüzleri

Yıllardır .NET ekosisteminde yeni bir Web API projesi oluşturduğumuzda karşımıza çıkan ilk şey neydi? Tabii ki o ikonik yeşil-yeşil tasarımlı, sadık dostumuz Swagger UI ekranı. Ancak teknoloji dünyası hızla değişiyor ve geliştirici deneyimi (Developer Experience - DX) standartları her geçen gün yükseliyor.

.NET 9'un yayınlanmasıyla birlikte Microsoft, yıllardır varsayılan olarak sunduğu Swashbuckle (Swagger) desteğini şablonlardan kaldırdı. Peki şimdi ne olacak? Sahneye, API dokümantasyonunu adeta bir sanat eserine dönüştüren ve içinde yerleşik bir Postman barındıran modern alternatif Scalar çıkıyor!

Bu yazıda, Swagger'ın neden emekliye ayrıldığını, Scalar'ın sunduğu devrimsel özellikleri ve .NET 9 projelerinize Scalar'ı nasıl saniyeler içinde entegre edebileceğinizi inceleyeceğiz.

.NET 9 ve Swagger'ın Sonu: Neler Değişti?

Microsoft, .NET 9 ile birlikte harici bir kütüphane olan Swashbuckle.AspNetCore bağımlılığını varsayılan proje şablonlarından çıkarma kararı aldı. Bunun arkasında birkaç temel neden bulunuyor:

1. Bakım Sorunları: Swashbuckle kütüphanesi uzun süredir aktif olarak güncellenmiyordu ve modern .NET özelliklerine ayak uydurmakta zorlanıyordu.
2. Yerel OpenAPI Desteği: .NET 9, artık kendi yerleşik OpenAPI doküman oluşturma desteğini (Microsoft.AspNetCore.OpenApi) sunuyor. Yani .NET, dışa bağımlı olmadan kendi OpenAPI JSON dosyasını üretebiliyor.

Bu durum, üretilen bu OpenAPI JSON dosyasını görselleştirecek yeni, modern ve performanslı arayüzlerin önünü açtı. İşte tam bu noktada Scalar devreye giriyor.

Scalar Nedir?

Scalar, OpenAPI (Swagger) spesifikasyonlarınızı alıp, inanılmaz derecede şık, modern ve etkileşimli bir API dokümantasyonuna dönüştüren açık kaynaklı bir kullanıcı arayüzüdür.

Scalar'ı sadece bir "doküman okuyucu" olarak tanımlamak haksızlık olur. Scalar, tarayıcınızın içinde çalışan güçlü bir API istemcisidir (API Client). Tasarımı ve sunduğu özelliklerle Postman, Insomnia veya Bruno gibi araçları aratmaz.

Neden Scalar? Öne Çıkan Özellikler

Scalar, klasik Swagger UI ile kıyaslandığında çağ atlamış bir geliştirici deneyimi sunuyor:

• Postman Benzeri Entegre İstemci: İsteklerinizi gönderebilir, header'ları, query parametrelerini ve request body'yi tıpkı profesyonel bir API istemcisinde olduğu gibi kolayca düzenleyebilirsiniz.
• Göz Alıcı Hazır Temalar: Dark mode (Karanlık tema) başta olmak üzere, "Purple", "Solarized", "Deep Space" gibi harika hazır temalarla birlikte gelir.
• Zengin Kod Örnekleri (Code Snippets): API tüketicileriniz için C# (HttpClient, RestSharp), JavaScript (Fetch, Axios), Python, Go, Java ve daha onlarca dilde hazır entegrasyon kodlarını otomatik üretir.
• Üstün Performans: Binlerce satırlık devasa OpenAPI dokümanlarını bile tarayıcıyı kasmadan, anında ve akıcı bir şekilde render eder.
• Kolay Arama ve Navigasyon: API uç noktaları arasında kaybolmanızı engelleyen gelişmiş bir arama (Search) barına sahiptir.

.NET 9 Projesine Scalar Nasıl Entegre Edilir? (Adım Adım)

Scalar'ı yeni veya mevcut bir .NET 9 Web API projesine entegre etmek son derece basittir. Gelin adım adım bunu nasıl yapacağımıza bakalım.

Adım 1: Gerekli Paketleri Yükleyin

Öncelikle projenize .NET'in yerel OpenAPI desteğini ve Scalar paketini eklemeniz gerekir. Terminalinizi açın ve şu komutları çalıştırın:

dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Scalar.AspNetCore

Adım 2: Program.cs Dosyasını Yapılandırın

Şimdi Program.cs dosyanıza giderek OpenAPI servislerini kaydedelim ve Scalar arayüzünü middleware olarak ekleyelim:

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// 1. Yerleşik OpenAPI desteğini servis olarak ekleyin
builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // 2. OpenAPI JSON endpoint'ini aktif edin (/openapi/v1.json)
    app.MapOpenApi();

    // 3. Scalar API Reference arayüzünü eşleyin
    app.MapScalarApiReference(options =>
    {
        options
            .WithTitle("Modern API Dokümantasyonum")
            .WithTheme(ScalarTheme.Purple) // Favori temanızı seçin
            .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient); // Varsayılan kod örneği
    });
}

app.MapGet("/api/v1/users", () => new[] { 
    new { Id = 1, Name = "Ahmet Yılmaz" },
    new { Id = 2, Name = "Ayşe Kaya" }
})
.WithName("GetUsers")
.WithDescription("Sistemdeki tüm kullanıcıları listeler.");

app.Run();

Adım 3: Projeyi Çalıştırın

Projenizi çalıştırın ve tarayıcınızdan https://localhost:XXXX/scalar/v1 adresine gidin. Karşınızda geleneksel, sıkıcı tablolar yerine; sol tarafında akıcı bir navigasyon menüsü, ortasında detaylı API açıklamaları ve sağ tarafında ise istek atabileceğiniz harika bir test konsolu olan modern Scalar arayüzünü göreceksiniz!

Swagger UI vs. Scalar: Karşılaştırma Tablosu

Sonuç: Geleceğe Adım Atın

Swagger uzun yıllar boyunca geliştirici dünyasına sadakatle hizmet etti ve endüstri standardı haline geldi. Ancak günümüz standartlarında geliştirici deneyimi (DX) artık çok daha kritik bir rol oynuyor.

.NET 9 ile birlikte gelen bu köklü değişim, API dokümantasyonlarımızı modernize etmek için mükemmel bir fırsat sunuyor. Scalar, sadece şık görünmekle kalmıyor; sunduğu yerleşik API istemcisi ve kod örnekleriyle API'lerimizi kullanan diğer yazılımcıların da hayatını kolaylaştırıyor.

Siz de projelerinizde Swagger'ın eskiyen arayüzüne veda edip Scalar'ın modern dünyasına geçiş yapmayı unutmayın!

Peki siz Scalar hakkında ne düşünüyorsunuz? Projelerinizde kullanmaya başladınız mı? Yorumlarda deneyimlerinizi bizimle paylaşın!