.NET 9 ile Swashbuckle Ayrılığı: Swagger UI’yı OpenAPI ile Nasıl Sürdürürsünüz?

.NET 9’un geliştirici önizleme sürümleriyle birlikte dikkat çeken önemli bir değişiklik, varsayılan web API şablonlarından popüler Swagger/OpenAPI belgeleme kütüphanesi Swashbuckle’ın çıkarılması oldu. Bu durum, uzun süredir Swashbuckle kullanan birçok geliştirici için başlangıçta kafa karıştırıcı olsa da, aslında Microsoft’un .NET ekosisteminde API belgelemesine yönelik daha entegre ve modern bir yaklaşımın sinyalini veriyor. Peki, bu değişiklik ne anlama geliyor ve API’lerinizin etkileşimli Swagger UI belgelemesini kaybetmeden .NET 9’a nasıl adapte olabilirsiniz? Bu makalede, .NET 9’un yeni belgeleme stratejisini derinlemesine inceleyecek, Swashbuckle olmadan Swagger UI’ı projelerinize nasıl entegre edeceğinizi adım adım gösterecek ve en iyi uygulamalarla API geliştirme süreçlerinizi güçlendireceğiz. Amacımız, geçişi sorunsuz hale getirmek ve geleceğe dönük, sürdürülebilir bir API belgeleme çözümü sunmaktır.

Uzun yıllardır ASP.NET Core API projelerinin vazgeçilmez bir parçası olan Swashbuckle, geliştiricilerin RESTful API’leri için OpenAPI (eski adıyla Swagger) belgeleri oluşturmasını ve bunları etkileşimli Swagger UI arayüzünde sunmasını sağlayan güçlü bir kütüphaneydi. Basitliği ve geniş özelleştirme seçenekleri sayesinde, API’lerin belgelenmesi ve keşfedilmesi süreçlerini önemli ölçüde hızlandırdı. Ancak, .NET ekosistemi sürekli evrim geçirirken, Microsoft da platformun temel yeteneklerini geliştirerek dış bağımlılıkları azaltma ve daha bütünleşik çözümler sunma eğiliminde. .NET 9’da Swashbuckle’ın varsayılan şablonlardan çıkarılması, bu stratejik yönelimin bir yansıması olarak ortaya çıktı. Bu hamle, birçok geliştiricinin ilk başta bir kayıp gibi algılamasına neden olsa da, aslında .NET’in yerleşik OpenAPI yeteneklerinin artık yeterince olgunlaştığını ve hatta belirli senaryolarda Swashbuckle’a alternatif olabileceğini gösteriyor.

Peki, Swashbuckle’ın kaldırılması tam olarak ne anlama geliyor? Öncelikle, Swashbuckle’ın tamamen “ölmediğini” vurgulamak gerekir. Kütüphane hala mevcut ve .NET 9 projelerinde manuel olarak eklenebilir. Ancak, .NET 9 ve sonraki sürümlerde API belgelemesi için Microsoft’un tercih ettiği yol, platformun kendi bünyesindeki OpenAPI entegrasyonu ve Minimal API’ler gibi yeni nesil yaklaşımlarla daha sıkı bir uyum içinde olmak. Microsoft, özellikle Minimal API’ler için tip tabanlı OpenAPI desteğini güçlendirerek, geliştiricilerin kodlarına doğrudan yansıyan, daha az “boilerplate” kodu gerektiren bir belgeleme deneyimi sunmayı hedefliyor. Bu, API tanımlarının doğrudan C# kodundan türetilerek güncelliğini korumasını kolaylaştırıyor ve belgeleme sürecini daha “doğal” hale getiriyor.

Bu stratejik değişiklik, geliştiricilere daha yalın ve optimize edilmiş bir API geliştirme ve belgeleme süreci vaat ediyor. Daha az üçüncü taraf bağımlılığı, potansiyel olarak daha az yapılandırma karmaşası ve gelecekteki .NET sürümleriyle daha iyi entegrasyon anlamına gelebilir. Ayrıca, bu durum .NET geliştiricilerini OpenAPI Specification (OAS) standartlarını daha derinden anlamaya ve belgeleme süreçlerini daha bilinçli bir şekilde yönetmeye teşvik ediyor. Her ne kadar ilk başta bir alışma süreci gerektirse de, uzun vadede daha sağlam, bakımı kolay ve performanslı API projeleri inşa etmemize yardımcı olacak bir adım olarak görülebilir. Bu bölümün devamında, OpenAPI ve Swagger UI gibi temel kavramları daha yakından inceleyecek ve .NET 9’un bu konudaki yeni yaklaşımlarına değineceğiz. Böylece, bu değişimin ardındaki mantığı tam olarak kavrayabilir ve kendi projelerinizde doğru kararları alabilirsiniz.

OpenAPI, Swagger UI ve Swashbuckle: Aralarındaki Fark Nedir?

API belgeleme dünyasında sıkça karıştırılan ancak kritik farklılıklara sahip üç temel kavram vardır: OpenAPI Specification (OAS), Swagger UI ve Swashbuckle. .NET 9’daki değişiklikleri tam olarak anlayabilmek için bu kavramların her birinin ne anlama geldiğini ve birbirleriyle nasıl ilişkilendiğini netleştirmek hayati önem taşır. Öncelikle, temelleri sağlam bir şekilde oturtalım.

OpenAPI Specification (OAS), RESTful API’ler için dilagnostik ve makine tarafından okunabilir bir arayüz tanımlama standardıdır. Bir nevi API’nizin “kontratını” veya “mimar planını” JSON veya YAML formatında açıklayan bir şemadır. OAS, API’nin hangi endpoint’lere sahip olduğunu, bu endpoint’lerin hangi HTTP metotlarını desteklediğini (GET, POST, PUT, DELETE vb.), hangi parametreleri beklediğini (URL yolu, sorgu dizesi, başlık, gövde), hangi veri tiplerini döndüreceğini ve olası hata yanıtlarını detaylandırır. Bir API’nin tüm yeteneklerini standartlaştırılmış bir şekilde belgelemeyi amaçlar. Bu standardizasyon, farklı programlama dilleri ve platformlar arasında API’lerin kolayca keşfedilmesini, anlaşılmasını ve tüketilmesini sağlar. Bir OAS belgesi, kod üretiminden (client SDK’ları, sunucu iskeletleri), test araçlarına ve etkileşimli belgeleme arayüzlerine kadar birçok farklı araç tarafından kullanılabilir.

Swagger UI, OpenAPI Specification belgelerini görselleştiren, etkileşimli ve web tabanlı bir araçtır. Bir OAS belgesini (genellikle bir JSON dosyası olarak sunulur) alır ve bunu insan tarafından kolayca okunabilen, keşfedilebilir bir arayüze dönüştürür. Swagger UI sayesinde geliştiriciler ve API tüketicileri, API’nin tüm endpoint’lerini, parametrelerini ve örnek yanıtlarını tek bir web sayfasında görebilirler. Dahası, Swagger UI sadece pasif bir belge görüntüleyici değildir; API endpoint’lerine doğrudan web arayüzünden istek göndermenize ve yanıtları gerçek zamanlı olarak görmenize olanak tanır. Bu “deneyin” özelliği, API’nin nasıl çalıştığını anlamak ve test etmek için paha biçilmez bir kolaylık sunar. Swagger UI’ın kendisi bir JavaScript kütüphanesidir ve herhangi bir web uygulamasına entegre edilebilir.

Swashbuckle.AspNetCore ise, ASP.NET Core uygulamaları için özel olarak geliştirilmiş popüler bir NuGet paketidir. Temel görevi, ASP.NET Core API’lerinizdeki C# kodunu tarayarak otomatik olarak bir OpenAPI Specification belgesi (Swagger JSON) oluşturmaktır. Ayrıca, bu otomatik olarak oluşturulan belgenin sunulması için Swagger UI’ı uygulamanıza entegre eder. Yani Swashbuckle, kodu OpenAPI’ye dönüştürme ve Swagger UI’ı yayınlama görevlerini bir araya getiren bir köprü görevi görür. Geliştiricilerin elle OpenAPI belgesi yazma zahmetinden kurtulmasını ve kod değişiklikleriyle belgelerin otomatik olarak güncel kalmasını sağlar. İçerisinde Swashbuckle.AspNetCore.Swagger, Swashbuckle.AspNetCore.SwaggerGen ve Swashbuckle.AspNetCore.SwaggerUI gibi farklı bileşenler barındırır. .NET 9’da şablonlardan çıkarılmasına rağmen, .NET 9 uygulamalarına manuel olarak eklenebilir ve çalışmaya devam edebilir. Ancak, Microsoft’un yerel OpenAPI desteği, Swashbuckle’ın sunduğu otomasyonun bir kısmını kendi bünyesine katmıştır.

Özetle:

• OpenAPI Specification (OAS): API’nin tanımını içeren bir standart (JSON/YAML dosyası).
• Swagger UI: OAS belgesini görselleştiren ve etkileşimli hale getiren web tabanlı araç.
• Swashbuckle: ASP.NET Core’da C# kodundan OAS belgesi üreten ve Swagger UI’ı entegre eden kütüphane.

Bu ayrımları anladıktan sonra, .NET 9’un Swashbuckle’ı kaldırmasının aslında API belgeleme yeteneğini kaybetmek değil, bu yeteneği farklı bir yolla, genellikle daha yerel ve entegre bir biçimde sağlamak olduğu anlaşılacaktır. Bir sonraki bölümde, .NET 9’un bu yeni yerel belgeleme stratejilerini ve Microsoft’un bu konudaki genel yönelimini detaylandıracağız.

.NET 9 ve API Belgeleme Stratejisi: Yeni Nesil Yaklaşımlar ve Microsoft’un Yönü

.NET 9 ile birlikte Microsoft, API belgeleme konusunda daha entegre ve “ürün içi” çözümlere odaklanarak geliştirici deneyimini basitleştirmeyi hedefliyor. Bu yeni stratejinin temelinde, OpenAPI Specification’ın (OAS) doğrudan platformun içine derinlemesine entegrasyonu yatıyor. Daha önceki .NET Core sürümlerinde de bazı temel OpenAPI yetenekleri bulunsa da, .NET 9 ile bu yetenekler özellikle Minimal API’ler bağlamında önemli ölçüde güçlendirildi ve geliştirildi. Microsoft’un bu yöndeki adımları, geliştiricilerin üçüncü taraf kütüphanelere olan bağımlılıklarını azaltarak, daha tutarlı ve sürdürülebilir bir API geliştirme ve belgeleme iş akışı sunma amacı taşıyor.

Bu yeni stratejinin en belirgin özelliklerinden biri, Microsoft.AspNetCore.OpenApi NuGet paketinin ve .NET 9 şablonlarında varsayılan olarak gelen ilgili yapılandırmaların artan önemi. Bu paket, API’nizin endpoint’lerini, parametrelerini ve yanıt tiplerini kodunuzdan otomatik olarak türeterek standart bir OpenAPI belgesi oluşturma yeteneğini temel bir bileşen olarak sunar. Özellikle Minimal API’lerde, rotaların ve işleyici fonksiyonlarının tanımından yola çıkarak OpenAPI şemasını oluşturmak artık çok daha doğal ve kolay. Örneğin, bir Minimal API’de bir parametrenin tipi veya bir dönüş değeri, doğrudan OpenAPI belgesine yansır. Bu “tip tabanlı OpenAPI” yaklaşımı, belgelerin her zaman kodla senkronize kalmasını sağlıyor, ki bu da manuel belge güncellemelerinin neden olduğu tutarsızlıkları büyük ölçüde ortadan kaldırıyor.

AddOpenApiDocument() metodu ve MapSwagger() veya UseSwaggerUI() uzantı metotları, bu yeni stratejinin merkezinde yer alıyor. AddOpenApiDocument() metodu, uygulamanızın servislere OpenAPI dokümanı oluşturma yeteneğini eklerken, UseSwaggerUI() ise bu dokümanı tarayıcıda görselleştirmek için Swagger UI’ı etkinleştiriyor. Önemli olan, bu bileşenlerin artık .NET ekosisteminin birinci sınıf vatandaşları olarak kabul edilmesi ve Microsoft tarafından doğrudan desteklenmesidir. Bu durum, gelecekteki .NET güncellemeleriyle uyumluluğun ve performans optimizasyonlarının daha iyi olacağı anlamına geliyor. Ayrıca, Minimal API’lerin getirdiği sadeleştirilmiş yapı, belgeleme kodunun da daha okunabilir ve yönetilebilir olmasını sağlıyor.

Microsoft’un bu stratejisi, sadece mevcut API’lerin belgelenmesini kolaylaştırmakla kalmıyor, aynı zamanda yeni ortaya çıkan konseptlerle de uyum sağlıyor. Örneğin, .NET Aspire gibi bulut tabanlı uygulamalar geliştirmeyi hedefleyen yeni platformlarda, API’lerin keşfedilebilirliği ve otomatik belgelenmesi kritik bir rol oynuyor. .NET 9’daki bu yerel OpenAPI desteği, Aspire gibi platformlarla sorunsuz entegrasyon için sağlam bir temel oluşturuyor. Geliştiriciler, daha az üçüncü taraf bağımlılığıyla çalışarak projelerinin karmaşıklığını azaltabilir ve platformun sunduğu yerleşik araçlardan maksimum verim alabilirler.

Öte yandan, mevcut Swashbuckle kullanıcıları için bu geçişin bazı adaptasyon süreçleri olabileceği aşikardır. Özellikle karmaşık özelleştirmelere veya özel Swagger filtrelerine sahip projelerde, yerel OpenAPI entegrasyonuna geçiş biraz daha fazla efor gerektirebilir. Ancak genel itibarıyla, Microsoft’un bu yeni belgeleme stratejisi, .NET API geliştiricileri için daha basit, daha entegre ve geleceğe dönük bir yol çiziyor. Sonraki bölümde, bu yeni yaklaşımı pratik bir şekilde nasıl uygulayacağınızı adım adım gösterecek ve kod örnekleriyle konuyu somutlaştıracağız. Böylece, .NET 9’da Swashbuckle olmadan Swagger UI’ı nasıl hayata geçirebileceğinizi net bir şekilde görebileceksiniz.

Adım Adım Uygulama: .NET 9 Projelerinizde Swashbuckle Olmadan Swagger UI Kurulumu

.NET 9’a geçerken veya yeni bir .NET 9 projesi başlatırken, Swashbuckle bağımlılığından kurtulup Microsoft’un yerel OpenAPI entegrasyonunu ve Swagger UI’ı nasıl kullanacağınızı öğrenmek, modern API geliştirme pratiklerinin önemli bir parçasıdır. Bu bölümde, hem varolan bir projeyi güncelleme hem de sıfırdan yeni bir proje oluşturma senaryoları için adım adım rehberlik sunacağız.

Varolan Projeyi .NET 9’a Güncellemek ve Swashbuckle’dan Ayrılmak

Eğer .NET 6 veya .NET 7 gibi önceki sürümlerden .NET 9’a yükselttiğiniz bir projeniz varsa ve bu projede Swashbuckle kullanıyorsanız, geçiş süreci biraz dikkat gerektirebilir. İlk adım, projenizin hedef framework’ünü .NET 9 olarak güncellemek olacaktır. Daha sonra, csproj dosyanızdaki Swashbuckle paketlerini (genellikle Swashbuckle.AspNetCore veya ilgili alt paketleri) kaldırmanız gerekecektir.

Ardından, Program.cs dosyanızda Swashbuckle ile ilgili tüm yapılandırma kodlarını (AddSwaggerGen, UseSwagger, UseSwaggerUI metodları ve varsa custom Swagger filtreleri) kaldırmalısınız. Bu temizlik, projenizi Microsoft'un native OpenAPI desteğine hazırlayacaktır. Eğer Minimal API'ler yerine geleneksel Controller tabanlı API'ler kullanıyorsanız, Microsoft.AspNetCore.OpenApi paketini eklemeniz gerekebilir.

Yeni Bir .NET 9 Projesinde Swagger UI'ı Sıfırdan Kurmak

Şimdi, en yaygın senaryo olan yeni bir .NET 9 Minimal API projesi oluşturarak süreci adım adım inceleyelim.

1. Proje Oluşturma:
   Komut satırını açın ve yeni bir .NET Web API projesi oluşturun.

   
   dotnet new web -n MyOpenApiApp --output MyOpenApiApp
   cd MyOpenApiApp
           

   
   Bu komut, Minimal API'leri kullanan yeni bir proje oluşturacaktır. .NET 9 şablonları artık varsayılan olarak Swashbuckle içermediği için, proje başlangıçta Swagger UI'dan yoksun olacaktır.

2. Gerekli NuGet Paketlerini Ekleme:
   Microsoft'un yerel OpenAPI desteğini kullanmak için Microsoft.AspNetCore.OpenApi paketini eklemelisiniz. Bu paket, OpenAPI belgelerini oluşturmak için gerekli altyapıyı sağlar.

   
   dotnet add package Microsoft.AspNetCore.OpenApi
           

   
   Bu paket, hem belgeleme şemasını üretmenize yardımcı olur hem de Swagger UI'ı uygulamanıza dahil etmek için gerekli entegrasyonları içerir.

3. Program.cs Dosyasını Yapılandırma:
   Şimdi, Program.cs dosyanızı açın ve aşağıdaki kod bloklarını ekleyin veya mevcut Minimal API tanımlamalarınızı güncelleyin.

   
   var builder = WebApplication.CreateBuilder(args);
   
   // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
   // 1. OpenAPI belgeleme servislerini ekle
   builder.Services.AddEndpointsApiExplorer();
   builder.Services.AddSwaggerGen(); // Bu metot, Microsoft.AspNetCore.OpenApi paketi ile birlikte gelir ve Swagger UI için gerekli altyapıyı sağlar.
   
   var app = builder.Build();
   
   // Configure the HTTP request pipeline.
   if (app.Environment.IsDevelopment())
   {
       // 2. Swagger UI'ı geliştirme ortamında etkinleştir
       app.UseSwagger(); // OpenAPI JSON belgesini sunar
       app.UseSwaggerUI(); // Swagger UI web arayüzünü etkinleştirir
   }
   
   app.UseHttpsRedirection();
   
   // Örnek bir Minimal API endpoint'i
   app.MapGet("/hello", () => "Merhaba .NET 9!");
   
   // Örnek bir API endpoint'i (daha fazla detay ve etiketleme ile)
   app.MapGet("/products/{id}", (int id) =>
   {
       // Ürün veritabanından ürün çekme simülasyonu
       var product = new { Id = id, Name = $"Product {id}", Price = 19.99m };
       return Results.Ok(product);
   })
   .WithName("GetProductById") // Endpoint'e özel bir isim verir
   .WithOpenApi(operation => // OpenAPI tanımını özelleştir
   {
       operation.Summary = "Belirli bir ürünü ID ile getirir.";
       operation.Description = "Ürün kataloğundan ID'ye göre tek bir ürün döndürür.";
       return operation;
   })
   .WithTags("Products"); // Endpoint'i bir grup altında etiketler (Swagger UI'da gruplama için)
   
   app.Run();
           

   Yukarıdaki kodda, AddEndpointsApiExplorer() Minimal API'ler için endpoint keşfini etkinleştirirken, AddSwaggerGen() OpenAPI şemasının oluşturulmasını ve UseSwagger() ile UseSwaggerUI() ise bu şemanın sunulmasını sağlar. Özellikle WithOpenApi() metodu, Minimal API endpoint'lerinize özel OpenAPI detayları eklemenize olanak tanır. WithTags() ise Swagger UI'da ilgili endpoint'leri gruplamak için kullanılır.

4. Uygulamayı Çalıştırma ve Test Etme:
   Projenizi çalıştırın:

   
   dotnet run
           

   
   Uygulamanız çalıştıktan sonra, genellikle https://localhost:7xxx/swagger adresinden Swagger UI'a erişebilirsiniz. Tarayıcınızda açtığınızda, API endpoint'lerinizin listelendiği, etkileşimli bir arayüz görmelisiniz. Minimal API'leriniz, GetProductById gibi adlandırılmış endpoint'leriniz ve özel açıklamalarınız burada görünecektir.

Gördüğünüz gibi, Swashbuckle olmadan da .NET 9 projelerinizde tam işlevsel bir Swagger UI deneyimi oluşturmak oldukça basittir. Microsoft'un yerel entegrasyonu, daha az bağımlılıkla ve daha doğrudan bir yaklaşımla API belgelemenizi sağlar. Bu yöntem, özellikle Minimal API'lerin sadeliğiyle çok iyi uyum sağlar ve gelecekteki .NET sürümlerinde API belgeleme için standart yaklaşım olmaya adaydır. Sonraki bölümde, bu yaklaşımları büyük ölçekli bir kurumsal API senaryosunda nasıl uygulayabileceğimize dair bir vaka analizine odaklanacağız.

Vaka Analizi: Büyük Bir Kurumsal API'nin .NET 9'a Geçişi ve Belgeleme Süreci

Birçok kurumsal uygulama, zamanla büyüyen ve karmaşıklaşan API setlerine sahiptir. Bu API'ler genellikle birden fazla ekip tarafından geliştirilir, farklı servisleri bir araya getirir ve uzun süredir üretimde olan projelerdir. Böyle bir projenin .NET 9'a geçişi ve API belgeleme stratejisinin güncellenmesi, sadece kod değişikliklerinden ibaret olmayan, aynı zamanda mimari ve süreçsel kararları da içeren kapsamlı bir süreçtir. Bu vaka analizinde, "TechCorp" adlı hayali bir şirketin, eski bir .NET 7 tabanlı e-ticaret mikroservis API'sini .NET 9'a taşıma ve Swashbuckle bağımlılığından kurtulma hikayesini inceleyeceğiz.

Senaryo: TechCorp'un E-ticaret API'si

TechCorp'un ana API'si, ürün katalog yönetimi, kullanıcı profilleri, sipariş işleme ve ödeme entegrasyonları gibi birçok farklı mikroservisi yöneten bir Gateway API'ydi. Bu API, .NET 7 üzerinde geliştirilmiş olup, tüm belgeleme süreçleri Swashbuckle.AspNetCore paketi üzerinden yönetiliyordu. Proje büyüdükçe, Swashbuckle'ın sunduğu esneklik takdir edilse de, bağımlılık güncellemeleri, bazen karmaşık özelleştirmelerin getirdiği performans yükleri ve .NET'in kendi içinde gelişen yeteneklerle çakışmalar gibi küçük sorunlar yaşanıyordu. Özellikle, ekip yeni Minimal API'ler ve gRPC gibi teknolojilere yöneldikçe, belgeleme stratejisinde daha hafif ve entegre bir çözüm arayışı doğmuştu.

Problemler ve Zorluklar

1. Bağımlılık Yönetimi: Swashbuckle'ın düzenli olarak güncellenmesi ve bazen .NET SDK güncellemeleriyle uyumsuzluk yaşaması, CI/CD süreçlerinde beklenmedik hatalara yol açabiliyordu.
2. Performans Endişeleri: Özellikle çok sayıda endpoint ve karmaşık veri modelleri olan büyük API'lerde, Swashbuckle'ın başlangıçtaki OpenAPI belgesi oluşturma süresi, uygulamanın ilk açılış süresini etkileyebiliyordu.
3. Özelleştirme Karmaşası: Swagger UI'ı kurumsal kimliğe uygun hale getirmek veya spesifik güvenlik gereksinimlerini (örn. çoklu kimlik doğrulama şemaları) yansıtmak için yazılan özel filtreler ve middleware'ler, kod tabanında karmaşıklığı artırıyordu.
4. Yeni Teknolojilerle Uyum: Minimal API'lerin benimsenmesiyle, geleneksel Controller tabanlı Swashbuckle entegrasyonu bazen Minimal API'lerin sadeliğiyle çelişiyordu.

Çözüm: .NET 9'a Geçiş ve Yerel OpenAPI Entegrasyonu

TechCorp ekibi, .NET 9'a geçişi sadece bir versiyon yükseltmesi olarak değil, aynı zamanda API belgeleme stratejilerini modernize etme fırsatı olarak gördü. Aşağıdaki adımlar izlendi:

1. Hedef Framework Güncellemesi: Tüm projeler, Target Framework olarak .NET 9 olarak ayarlandı.
2. Swashbuckle Temizliği: Mevcut tüm Swashbuckle paketleri csproj dosyalarından kaldırıldı. Program.cs ve Startup.cs (eğer varsa) dosyalarındaki AddSwaggerGen, UseSwagger ve UseSwaggerUI çağrıları ile ilgili tüm konfigürasyon kodları temizlendi.
3. Microsoft.AspNetCore.OpenApi Entegrasyonu: Projeye Microsoft.AspNetCore.OpenApi NuGet paketi eklendi.
4. API Explorer ve SwaggerGen Kurulumu: Program.cs dosyasına aşağıdaki yapılandırma eklendi:

   
   // ... mevcut kodlar ...
   builder.Services.AddEndpointsApiExplorer();
   builder.Services.AddSwaggerGen(options =>
   {
       // API versiyonlama için bilgi ekleme
       options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "TechCorp API v1", Version = "v1" });
       options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "TechCorp API v2", Version = "v2" });
   
       // JWT kimlik doğrulaması desteği ekleme
       options.AddSecurityDefinition("Bearer", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
       {
           In = Microsoft.OpenApi.Models.ParameterLocation.Header,
           Description = "Lütfen 'Bearer token' formatında token'ınızı girin",
           Name = "Authorization",
           Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
           Scheme = "Bearer"
       });
   
       options.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement
       {
           {
               new Microsoft.OpenApi.Models.OpenApiSecurityScheme
               {
                   Reference = new Microsoft.OpenApi.Models.OpenApiReference
                   {
                       Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,
                       Id = "Bearer"
                   }
               },
               Array.Empty()
           }
       });
   
       // XML yorumlarını dahil etme (API dokümantasyonunuzu zenginleştirmek için)
       var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
       options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
   });
   
   var app = builder.Build();
   
   if (app.Environment.IsDevelopment())
   {
       app.UseSwagger();
       app.UseSwaggerUI(options =>
       {
           options.SwaggerEndpoint("/swagger/v1/swagger.json", "TechCorp API v1");
           options.SwaggerEndpoint("/swagger/v2/swagger.json", "TechCorp API v2");
           options.RoutePrefix = "api-docs"; // Varsayılan "swagger" yerine "api-docs" kullan
       });
   }
   // ...
           

5. Endpoint'leri Güncelleme: Mevcut Controller'larındaki ve yeni eklenen Minimal API'lerindeki endpoint'ler, WithTags, WithSummary, WithDescription ve WithOpenApi gibi metotlar kullanılarak OpenAPI belgelemesi için zenginleştirildi. Örneğin, ürün listeleme endpoint'i şu şekilde güncellendi:

   
   app.MapGet("/api/v1/products", () =>
   {
       // Ürünleri veritabanından çekme mantığı
       var products = new List {
           new { Id = 1, Name = "Laptop", Price = 1200m },
           new { Id = 2, Name = "Mouse", Price = 25m }
       };
       return Results.Ok(products);
   })
   .WithName("GetAllProductsV1")
   .WithTags("Products", "V1") // Hem ürünler hem de versiyon 1 etiketi
   .WithSummary("Tüm ürünleri listeler (V1)")
   .WithDescription("Sistemdeki tüm ürünlerin temel bilgilerini döndürür.")
   .WithOpenApi(operation =>
   {
       operation.OperationId = "GetAllProductsV1";
       // Parametre ve dönüş tipleri otomatik olarak koddan türetilir.
       // İstenirse ek özelleştirmeler buradan yapılabilir.
       return operation;
   });
   
   // V2 versiyon için örnek bir endpoint
   app.MapGet("/api/v2/products", () =>
   {
       // ... V2 için ürün listeleme mantığı ...
   })
   .WithName("GetAllProductsV2")
   .WithTags("Products", "V2")
   .WithSummary("Tüm ürünleri listeler (V2) - Detaylı bilgi içerir.")
   .WithOpenApi();
           

Faydaları ve Sonuçlar

Bu geçişin TechCorp'a sağladığı temel faydalar şunlar oldu:

• Daha Az Bağımlılık: Proje, önemli bir üçüncü taraf bağımlılığından kurtuldu, bu da daha kolay bakım ve daha az uyumluluk sorunu anlamına geliyordu.
• Gelişmiş Performans: OpenAPI belgesi oluşturma süreci, platformun yerel yetenekleriyle daha optimize hale geldi.
• Daha Temiz Kod: Özellikle Minimal API'lerde, belgeleme kodunun doğrudan endpoint tanımlamalarının yanında olması, kodun okunabilirliğini ve yönetilebilirliğini artırdı.
• Geleceğe Hazırlık: Microsoft'un kendi araçlarını kullanmak, .NET Aspire gibi gelecekteki platform entegrasyonları için daha sağlam bir zemin oluşturdu.
• API Versiyonlama Kolaylığı: AddSwaggerGen içindeki SwaggerDoc yapılandırması sayesinde, API'nin v1 ve v2 versiyonlarının aynı Swagger UI arayüzünde kolayca gösterilmesi sağlandı.

TechCorp'un bu vaka analizi, .NET 9'daki belgeleme stratejisinin sadece yeni projeler için değil, aynı zamanda mevcut büyük ve karmaşık kurumsal API'ler için de uygulanabilir ve faydalı olduğunu göstermektedir. Adaptasyon süreci başlangıçta biraz çaba gerektirse de, uzun vadede daha sağlam, daha performanslı ve bakımı daha kolay bir API ekosistemi inşa etmeye yardımcı olmaktadır.

İleri Düzey İpuçları: .NET 9'da Swagger UI Deneyimini Özelleştirme ve Geliştirme

.NET 9 ile gelen yerel OpenAPI entegrasyonu, temel bir Swagger UI deneyimi sunsa da, gerçek dünya uygulamalarında genellikle daha fazla özelleştirme ve geliştirme ihtiyacı doğar. API'nizi tüketen geliştiriciler için daha zengin ve kullanışlı bir belgeleme sağlamak amacıyla, Swagger UI'ı çeşitli yollarla kişiselleştirebilirsiniz. İşte deneyimli kullanıcılar için bazı ileri düzey ipuçları ve püf noktaları:

API Versiyonlama (Versionowanie)

Büyük API'lerde versiyonlama olmazsa olmazdır. Swagger UI'da farklı API versiyonlarını göstermek, geliştiricilerin hangi versiyonu kullandıklarını anlamalarına ve eski versiyonlardan yeni versiyonlara geçişi takip etmelerine yardımcı olur. AddSwaggerGen metodu içerisinde birden fazla SwaggerDoc tanımlayarak bunu kolayca yapabilirsiniz:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API v1", Version = "v1" });
    options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API v2", Version = "v2" });
});

// Ardından UseSwaggerUI'da bu versiyonları referans gösterin
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "My API v2");
    options.RoutePrefix = string.Empty; // Kök dizinde yayınlamak için boş bırakılabilir
});

Endpoint'lerinizi de [ApiVersion("1.0")] gibi attribute'larla veya Minimal API'lerde WithTags("v1") gibi metotlarla etiketleyerek doğru versiyonlara atayabilirsiniz.

Authentication (JWT, API Key) Desteği

API'ler genellikle kimlik doğrulaması gerektirir. Swagger UI'ın bu kimlik doğrulama yöntemlerini desteklemesi, API'yi test etmeyi çok daha kolay hale getirir. JWT (Bearer Token) veya API Key kimlik doğrulamasını AddSwaggerGen içerisinde yapılandırabilirsiniz:

builder.Services.AddSwaggerGen(options =>
{
    // ... diğer SwaggerDoc ve XML yorumları ...

    options.AddSecurityDefinition("Bearer", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
    {
        In = Microsoft.OpenApi.Models.ParameterLocation.Header,
        Description = "Lütfen 'Bearer {token}' formatında JWT token'ınızı girin",
        Name = "Authorization",
        Type = Microsoft.OpenApi.Models.SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });

    options.AddSecurityRequirement(new Microsoft.OpenApi.Models.OpenApiSecurityRequirement
    {
        {
            new Microsoft.OpenApi.Models.OpenApiSecurityScheme
            {
                Reference = new Microsoft.OpenApi.Models.OpenApiReference
                {
                    Type = Microsoft.OpenApi.Models.ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty() // Bu endpoint için scopelar (API Key veya OAuth için gerekli olabilir)
        }
    });
});

Bu yapılandırma, Swagger UI arayüzünde bir "Authorize" düğmesi görünmesini sağlayacak ve kullanıcıların tokenlarını girerek güvenli endpoint'leri test etmelerine olanak tanıyacaktır.

Endpoint Gruplama ve Açıklamaları Zenginleştirme

Büyük API'lerde endpoint'leri mantıksal gruplara ayırmak, UI'ı daha okunabilir hale getirir. Minimal API'lerde WithTags() metodu bu işlevi görür:

app.MapGet("/users", () => "Kullanıcılar listesi")
    .WithTags("Kullanıcı Yönetimi");

app.MapPost("/products", () => "Ürün oluştur")
    .WithTags("Ürün Katalogu");

Ayrıca, WithSummary(), WithDescription() ve WithOpenApi() metotlarını kullanarak endpoint'lerinizin özetlerini, detaylı açıklamalarını ve hatta parametre/dönüş tipi açıklamalarını zenginleştirebilirsiniz. XML yorumlarını C# kodunuzda kullanmak ve bunları AddSwaggerGen'e IncludeXmlComments ile dahil etmek, API belgelerinizi otomatik olarak daha detaylı hale getirecektir.

builder.Services.AddSwaggerGen(options =>
{
    // ...
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

// Endpoint tanımı
/// 
/// Bu endpoint, sistemde yeni bir kullanıcı kaydı yapar.
/// Kullanıcı bilgileri.
/// Oluşturulan kullanıcının ID'si.
/// Kullanıcı başarıyla oluşturuldu.
/// Geçersiz kullanıcı verisi.
app.MapPost("/users", ([FromBody] UserDto user) =>
{
    // ... kullanıcı oluşturma mantığı ...
    return Results.Created($"/users/{user.Id}", user.Id);
})
.WithTags("Kullanıcı Yönetimi")
.Produces(201, typeof(int)) // 201 Created ve dönüş tipi
.Produces(400); // 400 Bad Request

Swagger UI'ı Özelleştirme ve Mobil Uyum (Custom CSS/JS)

Swagger UI'ın görünümünü ve davranışını tamamen özelleştirebilirsiniz. Kendi CSS veya JavaScript dosyalarınızı ekleyerek kurumsal kimliğinizi yansıtabilir veya ek fonksiyonellikler katabilirsiniz.

app.UseSwaggerUI(options =>
{
    // ... diğer seçenekler ...
    options.InjectStylesheet("/swagger-ui/custom.css"); // Özel CSS dosyanızı ekleyin
    options.InjectJavascript("/swagger-ui/custom.js"); // Özel JS dosyanızı ekleyin
});

Bu dosyaları wwwroot klasörünüzde barındırabilir ve uygulamanızın statik dosyalarını sunmasını sağlayan app.UseStaticFiles() middleware'ini eklemeyi unutmayın.

Mobil Uyum İçin İpuçları: Swagger UI varsayılan olarak responsive olsa da, bazı durumlarda özel dokunuşlar gerekebilir. custom.css dosyanızda medya sorguları (@media) kullanarak farklı ekran boyutları için özel stiller tanımlayabilirsiniz.

/* wwwroot/swagger-ui/custom.css içeriği */
.swagger-ui .topbar {
    background-color: #3f51b5; /* Marka rengi */
}

.swagger-ui .scheme-container {
    padding: 10px;
    border-radius: 5px;
}

/* Küçük ekranlar için medya sorgusu örneği */
@media (max-width: 768px) {
    .swagger-ui .wrapper {
        padding: 10px;
    }
    .swagger-ui .topbar-wrapper .link {
        display: none; /* Logo haricindeki linkleri gizle */
    }
    .swagger-ui .opblock-summary-method {
        min-width: 60px; /* Metot isimlerinin daha iyi görünmesini sağla */
    }
}

Bu, Swagger UI'ın mobil cihazlarda daha iyi bir kullanıcı deneyimi sunmasına yardımcı olacaktır.

Bu ileri düzey ipuçları, .NET 9'daki yerel OpenAPI entegrasyonuyla bile Swagger UI deneyiminizi bir sonraki seviyeye taşımanıza yardımcı olacaktır. API'nizin belgelemesi sadece bir gereklilik değil, aynı zamanda geliştirici deneyimini artıran önemli bir unsurdur.

Sonuç: .NET 9 ile Geleceğe Hazır API Belgeleme

.NET 9'un varsayılan şablonlarından Swashbuckle'ın çıkarılması, ilk başta şaşırtıcı gelse de, bu makalede detaylarıyla incelediğimiz gibi, aslında .NET ekosisteminde API belgelemesine yönelik daha stratejik ve bütünleşik bir yaklaşımın habercisi. Microsoft, yerel OpenAPI yeteneklerini güçlendirerek ve bunları özellikle Minimal API'lerle daha uyumlu hale getirerek, geliştiricilere daha az bağımlılık, daha temiz kod ve geleceğe daha hazır bir belgeleme çözümü sunuyor. Swashbuckle hala kullanılabilir bir seçenek olsa da, platformun kendi sunduğu araçları benimsemek, uzun vadede projenizin sürdürülebilirliği ve performansı açısından önemli avantajlar sağlayabilir.

Bu süreçte, OpenAPI Specification'ın bir standart, Swagger UI'ın bu standardı görselleştiren bir araç ve Swashbuckle'ın ise ASP.NET Core için bir otomasyon kütüphanesi olduğunu net bir şekilde anladık. .NET 9 ile birlikte, Microsoft.AspNetCore.OpenApi paketi ve ilgili metotlar (AddEndpointsApiExplorer, AddSwaggerGen, UseSwagger, UseSwaggerUI), kodunuzdan otomatik olarak OpenAPI belgesi oluşturma ve bunu etkileşimli bir Swagger UI üzerinden sunma görevini üstleniyor. Minimal API'lerin WithTags(), WithSummary() ve WithOpenApi() gibi uzantı metotları, belgeleme sürecini doğrudan API tanımlamalarının içine entegre ederek geliştirici deneyimini iyileştiriyor.

TechCorp örneğiyle de gördüğümüz üzere, mevcut büyük ölçekli projelerin .NET 9'a geçişi ve belgeleme stratejisinin güncellenmesi, başlangıçta bazı değişiklikler gerektirse de, daha az bağımlılık, daha iyi performans ve daha temiz bir kod tabanı gibi önemli faydalar sunuyor. Ayrıca, API versiyonlama, kimlik doğrulama entegrasyonu ve özel CSS/JS ile Swagger UI'ı kişiselleştirme gibi ileri düzey ipuçları, belgeleme deneyiminizi daha da zenginleştirmenize olanak tanıyor.

Sonuç olarak, .NET 9 ile API belgeleme, "Swashbuckle gitti, her şey bitti" demekten ziyade, "daha entegre, daha yerel ve daha esnek bir belgeleme çağı başlıyor" demektir. Bu yeni yaklaşımı benimseyerek, API'lerinizin sadece işlevsel değil, aynı zamanda mükemmel bir şekilde belgelenmiş ve keşfedilebilir olmasını sağlayabilirsiniz. Bu da hem kendi geliştirme ekibinizin verimliliğini artıracak hem de API'nizi tüketen harici geliştiriciler için sorunsuz bir deneyim sunacaktır.

Sıkça Sorulan Sorular (SSS)