AspNetCore 3.0 Swagger İmplementasyonu

AspNetCore ile Swagger kullanarak API dökümantasyonu oluşturma

0 2,364

Merhaba ,

A :  Arkadaşlar API de değişiklik mi oldu ?
B : Evet , Bazı değişiklikler yaptık.
A : Madde üzerinde değişiklik yorumunu göremiyorum ?

*******************

A : Save Post Methoduna hangi parametreleri göndermem gerekiyor ,  dönüş yapar mısın ?
B : İlk fırsatta dönüş yapıyorum.. ( Toplantı , acil problemler ) 4 Saat Sonra..
B : Parametreleri gönderdim..

********************

A : API yanlış sonuç dönüyor kontrol eder misin ?
B : Hangi parametreleri gönderiyorusun ?
– 3 saat sonra
B : ?????

troll

Yukarıda gün içinde sıklıkla duyduğunuz cümleler varsa bir şeyler ters gidiyordur.
Ekipler aynı ofisde hatta yan yana bile çalışsa bu tarz senkron bozuklukları her zaman olabiliyor.
Özetlemek gerekirse bir problemin tanımına ulaşmak veya argümanlarıyla birlikte problemi tanımlamak teknik anlamda çözümlenmesinden çok daha fazla zaman alıyor..

Bu makalemizde API methotlarının dokümantasyon ve test süreçlerinin iyileştirilmesi adına AspNet Core 3.0 üzerinde API ( dökümantasyon ve test süreçlerinin yönetilebilir olması açısından ) Swagger implementasyonunu inceleyeceğiz.

 

Swagger Nedir ?

Basit anlamda API servislerimizin dökümantasyonunun çıkartılması ve kolaylıkla response alınmasını sağlayan bir araçtır. Microsoft’un API projelerinde kısmı dökümantasyon çıkaran Help sayfasının yanısıra API Methotlarının gösterim şekli , uygulanabilirliği  , test edilebilir olması ve dökümantasyon işini dinamik bir şekilde özetleyebilmesi açısından oldukça ön plana çıkmıştır.

Swagger API endpoint adreslemesini dinamik bir şekilde yapmaktadır. Aslında özünde json formatında API method bilgiler içermektedir.  Methodun alacağı parametreler , tipleri , default geri dönüş tipi , endpoint url bilgisi kısacası tüm schema bilgisini saklamaktadır.

Aşağıda kullanacağımız uygulamanın swagger.json schema bilgilerine ulaşabilirsiniz..
https://localhost:44380/swagger/v1/swagger.json

 

Başlayalım

.NetCore 3.0 üzerinde Template API ile bir proje oluşturalım.
Projemize NugetPackageManager üzerinden Swashbuckle.AspNetCore Nuget’i yükleyelim.

SwaggerConfiguration

Sırasıyla Swagger Configürasyonu için gerekli kodları yazalım.

appsettings.json

Swagger için Route, Title ve EndPoint değerlerimizi config üzerinde parametrik olarak belirleyelim.

Startup.cs

Startup.cs sınıfı içerisinde ConfigureServices ve Configure methotlarında birkaç kural belirleyeceğiz.
Öncelikle appsetting.json üzerinde SwaggerOpt key ile tanımladığım parametreleri model üzerine Bind işlemini gerçekleştirelim.

SwaggerOpt ismiyle bir sınıf oluşturalım.

Configure methodu içerisinde;

GetSection ile config üzerinden swagger parametrelerini okuyacağız Bind ile swagger için oluşturduğumuz sınıfa aktaracağız.
Bind işlemi için swaggerOpt sınıfı değişkenleri appsetting.json üzerine tanımlanan parametrelerle aynı  olmalıdır.

Uygulamamızı swagger’dan haberdar etmemiz gerekiyor.  app.UseSwagger ve UseSwaggerUI bildirimlerini aşağıdaki gibi gerçekleştirebilirsiniz.

ConfigureServices metodu içerisinde;

 

 

Swagger için gerekli configurasyonlar tamamlandı, Şimdi Dummy Datayı generic bir yapıda implement edelim.

 

WeatherForecast Model

 

Generic IDummy<T> Data interface

 

WeatherForecastData sınıfımız

 

Tekrar startup.cs ‘e dönüp ConfigureServices metodu üzerinde oluşturduğumuz WeatherForecastData sınıfımızı Singleton ayaklandıralım.

Son adım olarak API Controller da methodlarımızı ekleyelim.
api/ControllerName/Method name şeklinde route belirledim.

api/WeatherForecast/Get
api/WeatherForecast/Post

 

Startup.cs içerisine eklediğimiz kodların son halini bütün şekişlde burada görebilirsiniz.

 

Projeyi ayaklandırıp , localhost üzerinden swagger ‘ı tetikleyebilirsiniz..
https://localhost:44380/swagger/index.html

Artık projemizde API dökümantasyonumuz mevcut. Makalemizin başında yazdığımız problemlerin çözümün için Swagger !

 

Get

NetCoreSwaggerImplementasyonu

Post

 

 

Email adresiniz yayınlanmayacaktır.