.NET 9 API'leri için Swagger'ı Değiştirmenin 4 Seçeneği

Standart Bir API Projesi Kurmak

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

Projenizin gerekli OpenAPI belge üretilmesini sağlamak için bir JSON dosya uç noktası ekleyen OpenAPI desteğini eklemek önemlidir.

Proje çalışmaya başladıktan sonra, Tim varsayılan OpenAPI belge URL'sine (örneğin, /swagger/v1/swagger.json) giderek açık OpenAPI özelliklerini inceler. Bu dosya, GET, POST ve DELETE gibi desteklenen fiiller de dahil olmak üzere, API uç noktalarınız hakkında yapılandırılmış metadata içerir.

İşlevsel olsa da, Tim, ham OpenAPI belgesini görüntülemenin kullanıcı dostu olmadığını belirtir. Geliştiricilerin ve tüketicilerin deneyimini zenginleştiren dört harici aracı göstermek için devam eder.

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

Swagger UI, artık varsayılan olarak dahil olmasa da, hala çok popüler bir araçtır. Tim, gerekli NuGet paketini kurarak nasıl geri getireceğini gösterir: dotnet: Swashbuckle.AspNetCore.SwaggerUI.

Swagger UI'yi yeni bir projede kurduktan sonra, 9:43'te, basitleştirilmiş bir sözdizimi kullanarak ara yazılımı yapılandırır ve başlama URL'sini /swagger olarak ayarlar. Bu UI, geliştiricilerin uç noktaları görebileceği, istek parametrelerini anlayabileceği ve bunları tarayıcıda test edebileceği kullanıcı dostu bir API belge arayüzü sağlar.

Swagger UI artık bir harici araç olsa da, hala OpenAPI özelliklerini destekler ve temel dokümantasyon ihtiyaçları için en iyi seçeneklerden biri olarak kalır.

Seçenek 2: ReDoc - Temiz, Salt Okunur API Belgesi

Tim'in ikinci aracı ReDoc'tur; bu araç, OpenAPI belgenizi temiz, salt okunur bir HTML sitesine dönüştürür. OpenAPI paketi Swashbuckle.AspNetCore.ReDoc'u ekledikten sonra belgeleri /api/docs'a eşler.

Swagger UI'den farklı olarak, ReDoc uç nokta testi yapmaya izin vermez. Ancak dış kullanıcılar ve müşteriler için uygun web tabanlı belge arayüzü olarak göze çarpar. Ana odak noktanız yalnızca REST API'lerini tanımlamak ve yapılandırılmış belgeleri sergilemekse, ReDoc mükemmel bir uyum sağlar.

ReDoc'un, beklenen yanıtlar, parametreler ve veri türlerini kapsayan sağlanan OpenAPI belgelerine dayalı olarak otomatik içerik oluşturduğuna dikkat etmekte fayda var. Bu, etkileşimden çok belgeler için optimize edilmiş yerleşik destek önceliği veren projelerle iyi uyum sağlar.

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

Sıradaki, Tim'in NSwag'a dalması, esnek ve zengin özelliklere sahip bir araç, APIs yalnızca belgelemekle kalmaz, aynı zamanda C#, TypeScript ve daha fazlası gibi çeşitli dillere müşteriler için kod da üretebilir. NSwag.AspNetCore NuGet paketini yükledikten sonra, Swagger-benzeri arayüzü kurar ve aynı JSON uç noktasına eşler.

Tim, NSwag'ın hem Swagger özelliklerini hem de OpenAPI standartlarını desteklediğini, geliştiricilere tercihlerine göre bir format seçme özgürlüğü sağladığını açıklar. UI, Swagger'a benzer görünse de, dış araç kütüphaneleri ve gelişmiş özellikler (otomatik müşteri yaratımı gibi) NSwag'ı öne çıkarır.

API'lerle entegre olurken manuel çabayı azaltmada NSwag'ın kod üretme yeteneği özellikle çoklu hizmetler veya harici araçlar içeren projelerde yardımcı olur. Güçlü bir çözüm sunar ve sağlam bir müşteri-üstü iletişim kurar.

Seçenek 4: Scaler - Tim'in API Testi İçin Favorisi

Tim, Scaler UI'yi tüm seçenekler arasında kişisel favorisi olarak tanıtıyor ve tarayıcıda Postman ve dokümantasyon karışımı olarak tanımlıyor. Scaler.AspNetCore paketini ekledikten sonra yalnızca bir satır kod (app.MapScalerApiReference()) arayüzü etkinleştirmek için yeterlidir.

Scaler, sorgu parametreleri, başlıklar ve çerezlerle istekleri yürütme dahil tam etkileşim desteği sunar. Ayırt edici özelliği, gerçek zamanlı geri bildirim - yanıt süresini, başlıkları ve sonuç taşıyıcılarını anında geri döndürür.

Scaler'ın öne çıkan bir özelliği, curl komutları ve farklı diller için müşteri kodu parçacıkları (PHP, Node, Python, C# ile HttpClient ve RestSharp aracılığıyla) oluşturma yeteneğidir. Tim, geliştirme sırasında API çağrılarını hızlıca kopyalayıp yapıştırmak için özellikle faydalı buluyor.

Scaler ayrıca hafif ve karanlık modlar arasında geçiş yapmayı sağlar, bu da onu kullanıcı dostu bir API belgeleme platformu yapar ve daha fazla gelişme için alan sağlar. Açık kaynaklı bir API platformu olarak, Scaler, aktif bir bakım ile birlikte topluluk ilgisiyle gelişmeye devam eder.

Son Düşünceler: Seçenekler Esneklik Sağlar

Videonun kapanış dakikalarında Tim, .NET web şablonlarından Swagger UI'yi kaldırmanın bir adım geri gibi görünebileceğini, ancak aslında modern, daha uygun çözümleri kucaklama fırsatı olduğunu vurguluyor. Bu değişiklik, Microsoft'un hızlı sürüm döngüleriyle uyum sağlar, özellikler daha modüler ve odaklı hale gelir.

OpenAPI desteği artık daha çok bir birinci sınıf destek gibi işlev görür, sert ve yerel bir uygulamadan ziyade. Scaler ile etkileşimli test, NSwag ile müşteri kodu üretimi veya ReDoc ile temiz çıktı olsun, projenizin ihtiyaçlarına bağlı olarak araçları karıştırmak ve eşleştirmek özgür olacaksınız.

Tim, geliştiricileri bu araçları keşfetmeye, hangi aracın iş akışlarına uygun olduğunu görmeye ve hatta farklı ortamlar için (örneğin, geliştirme ve halka açık dokümantasyon için ayrı kullanıcı arayüzleri kullanmaya) teşvik eder. Bu seçeneklerin tümü OpenAPI ve Swagger standartlarını desteklediği için, tek bir satıcıya veya iş akışına bağlı kalmazsınız.

Sonuç

.NET 9'da varsayılan olarak Swagger UI'nin kaldırılması sayesinde, geliştiriciler artık OpenAPI belgeleme ihtiyaçları için en iyi aracı seçme özgürlüğüne sahip. HTTP API'lerini belgeliyorsanız, dış araçlara hizmet veriyorsanız veya dahili geliştirmeyi destekliyorsanız, hedeflerinize uygun bir çözüm var.

Swagger UI, ReDoc, NSwag ve Scaler gibi araçlarla, API'leri belgelendirip test etmek hiç bu kadar özelleştirilebilir veya geliştirici dostu olmadı. Tim Corey'nin videosunda gösterdiği gibi, ihtiyaçınız olan, sadece birkaç paket, birkaç satır kod ve uygulamanıza ve takımınıza en iyi hizmet eden araçları keşfetme isteğidir.