NET 9 API'lerinde Swagger Yerine Kullanılabilecek 4 Seçenek

Standart Bir API Projesi Ayarlama

Tim, standart ASP.NET Core Web API şablonunu seçerek Visual Studio'da minimal bir API projesi oluşturarak başlıyor.

Projeye OpenAPI desteği eklemek için kutuyu işaretlemeyi vurgular; bu, gerekli OpenAPI belge oluşturma işlemini JSON dosya uç noktası üzerinden projeye dahil eder.

Proje çalıştırıldıktan sonra, Tim varsayılan OpenAPI belgesi URL'sine (örn. /swagger/v1/swagger.json) gider ve ham OpenAPI spesifikasyonlarına göz atar. Bu dosya, GET, POST ve DELETE gibi desteklenen fiil bilgileri de dahil olmak üzere, API uç noktalarınız hakkında yapılandırılmış meta veriler içerir.

Tim fonksiyonel olsa da, ham OpenAPI belgesini görüntülemenin kullanıcı dostu olmadığını not ediyor. Daha iyi bir web tabanlı dokümantasyon arayüzü sağlamak için geliştirici ve kullanıcı deneyimini artıran dört harici aracı göstermek üzere devam ediyor.

Seçenek 1: Swagger UI – Tanıdık Deneyim

Swagger UI hala çok popüler bir araç olsa da varsayılan olarak dahil değildir. Tim, gerekli NuGet paketi .NET: Swashbuckle.AspNetCore.SwaggerUI'yi kullanarak nasıl geri getireceğinizi gösterir.

Swagger UI'i yeni bir projede ayarlamayı tamamladıktan sonra, 9:43'te ara birimi, basitleştirilmiş söz dizimi ile yapılandırır ve /swagger URL'sini açılış adresi olarak ayarlar. Bu UI, geliştiricilerin uç noktaları görüntüleyebileceği, istek parametrelerini anlayabileceği ve tarayıcıda test edebilecekleri kullanıcı dostu bir API dokümantasyon arayüzü sunar.

Swagger UI artık harici bir araç olmasına rağmen, OpenAPI spesifikasyonlarını hala destekler ve geliştirme sırasında temel belgeleme ihtiyaçları için en iyi tercihlerden biri olmaya devam eder.

Seçenek 2: ReDoc – Temiz, Salt Okunur API Dokümantasyonu

Tim'in ikinci aracı ReDoc'dur, OpenAPI belgenizi cilalı, salt okunur bir HTML sitesi haline dönüştürür. Swashbuckle.AspNetCore.ReDoc OpenAPI paketini ekledikten sonra dokümantasyonu /api/docs yoluna mapler.

Swagger UI'den farklı olarak, ReDoc uç noktaları test etmeye izin vermez. Ancak, harici kullanıcılar ve müşteriler için uygun olan bir web tabanlı belgeleme arayüzü olarak parlıyor. Eğer odak noktanız sadece REST API'lerini tanımlamak ve yapılandırılmış belgeleri göstermekse ReDoc harika bir uyum sağlar.

ReDoc'un sağlanan OpenAPI spesifikasyonlarına göre otomatik olarak içerik oluşturduğuna, beklenen yanıtları, parametreleri ve veri türlerini kapsadığına dikkat etmek önemlidir. Bu, etkileşimden ziyade optimise edilmiş belgeleme sağlayan projelere iyi uyum sağlar.

Seçenek 3: NSwag – Dokümantasyon + Kod Üretimi

Sonra, Tim, NSwag'a dalıyor; bunun esnek ve özellik zengin bir araç olduğunu, API'leri sadece belgelemekle kalmayıp aynı zamanda C#, TypeScript ve daha fazla dilde istemci kodu üretebileceğini açıklıyor. NSwag.AspNetCore NuGet paketini kurduktan sonra Swagger benzeri bir arayüz ayarlar ve bu arayüzü aynı JSON uç noktasına bağlar.

Tim, NSwag'ın hem Swagger spesifikasyonlarını hem de OpenAPI standartlarını desteklediğini, bu sayede geliştiricilerin tercih edilen formatı seçmelerine olanak tanıdığını açıklar. UI, Swagger UI'ye benzer görünebilir, ancak NSwag'da parlayan, harici araç kitaplıkları ve gelişmiş özellikler (otomatik istemci oluşturma gibi) dir.

NSwag'ın kod oluşturma yeteneği, API'lerle entegrasyon sırasında, özellikle birden fazla hizmet veya harici araç içeren projeler için manuel çabayı azaltmada yardımcı olur. Bu, güçlü istemci-sunucu iletişimi kuran ekipler için güçlü bir çözümdür.

Seçenek 4: Scaler – Tim'in Favorisi API Testleri İçin

Tim, Scaler UI'yi seçenekleri arasında kişisel favorisi olarak tanıtarak, bunu tarayıcıda Postman ve dokümantasyon karışımı olarak tanımlar. Scaler.AspNetCore paketini ekledikten sonra, yalnızca bir satır kod (app.MapScalerApiReference()) ile arayüz etkinleştirilebilir.

Scaler, sorgu parametreleri, başlıklar ve çerezler ile isteklerin uygulanmasını içeren tam etkileşim desteği sağlar. Onu farklı kılan ise gerçek zamanlı geri bildirim – yanıt süresini, başlıkları ve sonuç yüklerini anında geri döndürür.

Scaler'ın önemli bir özelliği, farklı dillerde curl komutları ve istemci kod parçacıkları oluşturabilmesidir (PHP, Node, Python, C# HttpClient ve RestSharp ile). Tim, bu özelliği API çağrılarını geliştirme sırasında hızlıca kopyalayıp yapıştırabilmek için özellikle faydalı buluyor.

Scaler ayrıca, açık ve koyu mod arasında geçiş yapma seçeneği de sunarak, kullanıcı dostu bir API dokümantasyon platformu sağlar ve daha fazla geliştirme alanı bırakır. Açık kaynak bir API platformu olarak devam eden bakım ve güçlü topluluk ilgisi ile gelişmeye devam ediyor.

Son Düşünceler: Seçenekler Esneklik Getiriyor

Videonun kapanışında, Tim .NET web şablonlarından Swagger UI çıkışının bir geri adım gibi görünebileceğini ancak aslında modern, daha özel çözümleri benimseme fırsatını sağladığını belirtiyor. Bu değişiklik, Microsoft'un hızlı sürüm döngüleriyle uyumlu olup, özelliklerin daha modüler ve odaklanmış hale geldiği anlamına gelir.

OpenAPI desteği şu anda yerel bir uygulama olmaktan ziyade, birinci sınıf yurttaş desteği olarak davranıyor. Projenizin ihtiyaçlarına göre araçları karıştırma ve eşleştirme özgürlüğüne sahipsiniz—ister Scaler ile etkileşimli test, ister NSwag ile istemci kod üretimi, isterse ReDoc ile temiz çıktı.

Tim geliştiricileri, bu araçları keşfetmeye, hangisinin iş akışlarına en uygun olduğunu görmeye ve hatta farklı ihtiyaçlar için birden fazla UI uyguladıktan sonra kullanmaya teşvik ediyor. Tüm bu seçeneklerin OpenAPI ve Swagger spesifikasyonlarını desteklemesi, tek bir satıcıya veya iş akışına bağlı olmadığınız anlamına gelir.

Sonuç

.NET 9'da Swagger UI'nin varsayılan olarak kaldırılması ile birlikte, geliştiriciler artık OpenAPI belgelemesi ihtiyaçları için en iyi aracı seçme özgürlüğüne sahiptir. İster HTTP API'lerini belgeliyor olun, ister harici araçlar sunuyor olun ya da iç geliştirmeyi destekliyor olun, hedeflerinize uyan bir çözüm mevcut.

Swagger UI, ReDoc, NSwag ve Scaler gibi araçlarla API'leri belgelemek ve test etmek her zamankinden daha özelleştirilebilir ve geliştirici dostudur. Tim Corey'nin video içeriğinde gösterdiği gibi, birkaç paket, birkaç satır kod ve uygulamanıza ve ekibinize en iyi hizmet eden araçları keşfetme isteği yeterlidir.