Merhaba,
Uygulamalarımızda oldukça sık web servisleri kullanıyoruz ve oluşturmuş olduğumuz servislerin başkaları tarafından kullanılacağını düşününce kullanılan metotların ne iş yaptığı, hangi parametrelerle çalıştığı ya da yapılan sorgu sonucunda nasıl bir sonuç elde edileceğini belirten dokümanın hazırlanması ve her yeni bir metot eklendiğinde bu dokümanın güncellenmesi gerekmektedir.
İşte bu durumda Swagger hayat kurtarır dersem yanlış bir şey söylememiş olurum sanırım.
Swagger, yazılım dünyası tarafından kabul görmüş yaygın olarak kullanılan bir dinamik doküman oluşturma aracıdır. Projedeki tüm sorgu adreslerini yakalayabilmek için tüm controller ve controller içinde bulunan action metotlarımızı json dosyasında tutar ve bunu dokümantasyon için kullanılan Swagger-UI arayüzüne gönderir.
Böylece proje boyunca eklenen ya da değiştirilen metotlar dinamik olarak yakalanır ve güncellenir. Bu da biz geliştiricileri her seferinde doküman güncelleme maliyetinden kurtarır.
Swagger’ ı projemize entegre etmek için öncelikle Swashbuckle.AspNetCore NuGet paketini ekliyoruz.
Daha sonra Startup.cs ve launchSettings.json dosyalarını güncelliyoruz.
Uygulamamızı çalıştırdığımızda karşımıza projemize default olarak eklenen WeatherForecast controller ve bu controller içinde ekli olan Get metodunun dokümante edilmiş hali geldi.
Test edeceğiniz metoda tıklandığınızda ilgili ekran açılıyor ve burada bize metot hakkındaki bilgileri gösteriyor. Hangi parametreler ile çalışıyor, dönüş tipi ne oluyor vs.
“Try it out” düğmesine basıp sonrasında ekrana gelen “Execute” düğmesine bastığınızda ilgili metotu çalıştırıp metodunuzu test edebilirsiniz.
Projemize Swagger’ ı entegre etmiş olduk. Şimdi biraz daha özelleştirelim…
SwaggerDoc içerisinde yapmış olduğumuz eklemeler ile oluşturduğumuz Api’ ın versiyon bilgisi, başlığı, tanımı, iletişime geçilecek kişi bilgisi, lisans bilgisi gibi alanlarını güncellemiş olduk.
Örneğin uygulamanızda Bearer Token ile Authorization yaptığınız bir üyelik sisteminin olduğunu varsayalım. Bu durumda AddSwaggerGen içerisine AddSecurityDefinition ve AddSecurityRequirement tanımlamalarını ekliyoruz.
Son eklemelerimizden sonra uygulamamızı tekrar çalıştırdığımızda token bilgisinin girilebileceği “Authorize” düğmesi de eklenmiş oldu.
Artık üyelik gerektiren alanlar için ilgili authenticate metodu ile token alındıktan sonra “Authorize” düğmesine tıklanıp alınan token değerini girebileceğimiz bir alanımız olmuş oldu.
Şimdilik bu kadar…
Swagger’ ın diğer özelliklerini kullandıkça yazıyı güncelliyor olacağım.
Sağlıklı günler, görüşmek üzere…
Kaynaklar:
