Linux'ta .NET Aspire'a Swagger UI Ekleme

Swashbuckle NuGet Paketini Yükleme

[0:38 - 1:35] Tim, Tiny Ticket projesini VS Code'da açar ve API servisinin Program.cs koduna gider. API, zaten önceki bölümden GET /api/tickets uç noktasına sahip, ancak çağrı yapmak için URL'nin manuel olarak oluşturulması gerekiyordu. Doğru bir test arayüzü eklemek için ilk adım Swagger UI paketini yüklemektir.

API projesine sağ tıklayın, "NuGet Paketi Ekle" seçeneğini seçin ve Swashbuckle.AspNetCore.SwaggerUI arayın. Tim en son (kayıt sırasında 10.1.7) sürümü yüklüyor. Kurulumdan sonra paket referansı proje dosyasında görünür. Başka bir bağımlılık gerekmez çünkü proje zaten varsayılan Aspire hizmet yapılandırması ile OpenAPI desteğine sahiptir.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Program.cs'de Swagger UI'yı Yapılandırma

[1:35 - 3:12] Paket yüklendikten sonra, yapılandırma Program.cs geliştirme-yalnızca bloğuna girer. Proje, zaten OpenAPI spesifikasyon dosyasını çalışma zamanında üreten app.MapOpenApi() kaydedilmiş durumda. Swagger UI'nin sadece o dosyanın nerede olduğunu ve uç nokta grubunu nasıl etiketleyeceğini bilmesi gerekiyor.

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

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

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

SwaggerEndpoint çağrısı, .NET'in otomatik olarak ürettiği OpenAPI spesifikasyonuna işaret eder. İkinci parametre, Swagger UI açılır menüsünde görünen bir görüntüleme adıdır. Tim, bu üç satırın tüm Swagger kurulumunu içerdiğini vurgular. UI'yi özelleştirmek, uç noktaları gruplandırmak veya kimlik doğrulama başlıkları eklemek için daha fazla yapılandırma ekleyebilirsiniz, ancak bir geliştirme testi aracı için varsayılanlar yeterlidir.

Dikkate değer bir detay: .NET 9'dan beri yeni API projeleri artık varsayılan olarak Swagger içermiyor. Microsoft, doğal bir katman olarak OpenAPI'yi gönderip geliştiricilere tercih ettikleri UI katmanını seçme şansı vererek bu konuları ayırdı. Swagger, Scalar ve diğer araçlar aynı OpenAPI spec dosyasını tüketir, bu yüzden belirli bir görüntüleyiciye kilitlenmezsiniz.

Swagger Arayüzünü Çalıştırma ve Doğrulama

[3:12 - 6:07] Kaydedildikten sonra, Tim projeyi Çalıştırma ve Hata Ayıklama paneli üzerinden başlatır. Bir kez Aspire panosu yüklendiğinde ve API servisi çalışıyor olarak göründüğünde, API'nin URL'sine gider ve yola /swagger ekler.

Swagger UI "Ticket App API v1" etiketi ile yüklenir ve mevcut uç noktaları listeler. Kök uç noktası (/) basit bir sağlık mesajı döndürür ve /api/tickets, veritabanındaki bilet verilerini döndürür.

Tim kök uç noktada "Try it out"'a tıklayıp çalıştırır. Yanıt 200 durumu ve bir onay mesajıyla geri gelir. Sonra /api/tickets uç noktasına gidip yürütme düğmesine basar ve sorun giderme burada başlar.

İlk deneme SQL sunucusuna bağlantı kurma sırasında 'ağ ilişkili veya örnek spesifik bir hata oluştu' hatasıyla başarısız olur. Veritabanı konteyneri makine yeniden başlatıldıktan sonra başlamamıştı. Tim Portainer'ı açar, SQL Server Docker konteynerini bulur ve başlatır. Konteyner başlatmayı bitirdikten sonra Swagger'a geri döner ve isteği yeniden yürütür. Bu sefer, yanıt veritabanında saklanan üç test biletle 200 döner.

Bu dizi, birim testleri ve sahte verilerin yüzeye çıkaramayacağı sorunları, gerçek altyapıyla yapılan entegrasyon testlerinin yüzeye çıkaracağını pratik bir hatırlatma niteliğindedir. Veritabanı konteyneri, önyükleme sırasında otomatik başlatma olarak ayarlanmadığından, yeniden başlatmadan sonraki ilk API çağrısı, konteyner durumunu önce doğrulamazsanız başarısız olur.

Sonraki Adımlar: CRUD Uç Noktaları

[6:07 - 7:20] Tim serideki yaklaşan bölümlerin ön izlemesini sunar. Tiny Ticket API şu anda yalnızca GET /api/tickets uç noktasına sahiptir, bu da spTickets_GetAll saklı prosedüre eşlenir. Veritabanındaki kalan saklı prosedürler (ID'ye göre Getir, Ekle, Güncelle, Sil) için her biri doğru HTTP fiili ile eşleşen bir API uç noktasına ihtiyaç duyar: alın için GET, oluşturma için POST, güncellemeler için PUT ve kaldırma için DELETE.

Her uç noktanın aynı deseni izlediğini ve uygulanmasının kolay olduğunu belirtir, ancak yaklaşan videolar, her parçanın bağımsız olarak kolayca referans alınabilmesi için bunları teker teker inceleyecektir. Seriyi küçük, odaklanmış bölümlere ayırma seçimi, daha uzun bir videoya göz atmadan ihtiyacınız olan uç nokta türüne doğrudan atlayabilmenizi sağlar.

Sonuç

[7:20 - 7:24] Linux'ta bir .NET Aspire projesine Swagger UI eklemek için bir NuGet paketi ve Program.cs yapılandırmada üç satır gereklidir. OpenAPI spec dosyası, varsayılan Aspire hizmet ayarları tarafından zaten üretilir, bu yüzden Swagger yalnızca o dosyaya bir işaretçi ve bir ekran adı gerektirir. Bundan sonra, API'deki her uç nokta, ayrı bir istemci oluşturmadan tarayıcı üzerinden test edilebilir.

Tim'in, yeniden başlatma sonrasında karşılaştığı veritabanı bağlantı sorunu, pratik bir noktayı pekiştirir: geliştirme yığınınızda konteynerler bulunduğunda, API uç noktalarını test etmeden önce çalıştıklarından emin olun. Swagger, bu doğrulama için hızlı bir geri bildirim döngüsü sağlar.

Seri navigasyonu: Bu makale, Tiny Ticket uygulamasını oluşturan Linux üzerinde C# serisinin bir parçasıdır. Önceki: Linux Üzerinde .NET Aspire Kurulumu. Sonraki: Get By ID Uç Noktası Ekleme.

Örnek İpucu: Swagger yerine farklı bir OpenAPI görüntüleyiciyi tercih ediyorsanız, Scalar veya RapiDoc gibi bir paket yükleyin ve aynı /openapi/v1.json uç noktasına yönlendirin. Spec dosyası, UI'den bağımsızdır, bu yüzden görüntüleyiciyi API yapılandırmanızı değiştirmenize gerek kalmadan değiştirebilirsiniz.

Onun YouTube Kanalı üzerindeki tam videoyu izleyin ve Linux serisinde C# ile API'ler inşa etme üzerine daha fazla bilgi edinin.