Swagger UI Nedir? .Net Core 3.1'de Swagger UI Kullanımı

Web API geliştirirken API de yazılan metodların ne iş yaptığı? Hangi parametreleri aldığı? Ne cevap döndüğü? Gibi bilgilerin yer aldığı dökümanlar hazırlanması gerekir. Çünkü o API ile, uygulamasını haberleştiren yazılımcı, nasıl bir veri alıp göndereceğini bilmesi gerekir.İşte bu noktada Swagger UI devreye girmektedir.

Swagger UI, OpenAPI (Swagger) spesifikasyonu ile tanımlanan bir API için, dökümantasyonları görsel olarak oluşturan açık kaynaklı bir projedir. Swagger UI, GitHub’tan indirip kullanılabilirsiniz.

Swagger UI API’lere arayüz görevi görmektedir. Yazılımcıların nasıl bir entegrasyon yapacağını görmelerini sağlar. Swagger UI arayüzünü oluştururken verileri “swagger.json” dan okur. Eğer API’nizi Node.js ile yazıyorsanız maalesef “swagger.json” dosyasını kendiniz hazırlamanız gerekiyor(en son öyleydi yeni bir araç çıkmadıysa). Aşağıdaki örnek gibi.

Örnek bir Node.js Apisi için yazılmış swagger.json dosyası.

.Net Core tarafında ise işler biraz daha kolaylaştırılmış. “Swashbuckle.AspNetCore” Nuget paketi ile gelen dll’ler sizin için işi kolaylaştırıyor. Metodlarınızın ve Class’larınızın üzerine yazdığınız Summary’leri alıp “swagger.json”dosyasını sizin için otomatik oluşturuyor.

Projemize Swagger UI eklemek için aşağıdaki komut ile Nuget üzerinden ilgili kütüphaneyi ekliyoruz.

dotnet add package Swashbuckle.AspNetCore

Paketi indirdikten sonra ilgili ayarlar için, Startup.cs dosyasında aşağıdaki eklemeleri yapmamız gerekiyor.

AddSecurityDefinition ve AddSecurityRequirement metodlarını sistemdeki yetkilendirme yapısında, arayüz üzerinden atılan isteklerde token bilgisinin eklenebilmesi için ayar yapıyoruz.

Sistemde yetkilendirme yok ise 4. satırdaki kod yeterli olacaktır.

Configure Metodunda middleware’e Swagger UI eklemeyi unutmuyoruz.

app.UseSwagger();                                   app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "NetCoreExampleApi v1"));

Kurulum ve ayarlama işlemi bu kadar basit. Artık projeyi çalıştırabiliriz. Projeyi çalıştırıdığımızda tarayıcıda böyle bir ekran karşılıyor bizi.

Metodların türleri(Get,Post vs.) ile url yapıları renkli bir görsel ile çok güzel bir şekilde gösterilmiş. Class’ların şema yapısı da mevcut. Authorize butonuna tıklandığında token eklemek için bir pop-up açılacaktır.

Swagger UI üzerinden yapılan isteklerin Authorization Header’ına token eklemek için açılan pop-up.

Bu arayüz üzerinden ilgili methodlar test edilebilir. Apinin fonksiyonlarına veri gönderebilir ve veri çekebilirsiniz. Postman gibi programlara gerek kalmadan yazdığınız API’yi hızlıca test edebilirsiniz.

Bazen gözden kaçan ufak tefek durumlarda, Swagger UI sistemdeki dinamik oluşan “swagger.json” dosyasını okuyamaz.Bu hata aşağıdaki gibidir.

Bu hatanın sebep olduğu olayı şu şekilde açıklayabiliriz.
Aynı Controller içinde bulunan farklı iki metodun aynı Http metodu ile işratelenmesidir. Aşağıdaki örnekte iki metod da [HttpGet] atribütü ile işaretlenmiş.

[HttpGet] ile işaretlenmiş metodlar

Eğer Controller içinde 2 den fazla Http metod attribütü ile işaretlenmiş metod varsa,bunların url bilgilerini [Route(“”)] atribütü ile belirtmemiz gerekir. Yoksa Swagger UI url yapısına karar veremiyor. Aşağıdaki gibi olması gerekiyor.

[HttpGet] ve [Route(“”)] atribütleri ile işaretlenmiş metodlar

Elimden geldiğinde anlatmaya çalıştım. Umarım faydalı bir içerik olmuştur. Örnek Proje kodları buradan indirilebilir.

Kaynak:

https://swagger.io/tools/swagger-ui/