Swagger ve .Net Core 3.0

Merhaba arkadaşlar, bugün sizlerle beraber .net core 3.0 web api ve swagger entegrasyonunu yapacağız. Öncelikle swaggerdan biraz bahsedelim. Swagger, apilerimize ui desteği sağlayarak doğal bir dokümantasyon oluşturmamızı sağlayan ve OpenAPI bildirimlerine uyan açık kaynak bir araçtır. Apilerde contract denen alınacak request ve verilecek response sözleşmesini standart hale getirerek hem insanların hemde makinelerin anlayabileceği bir standart sunar.

Şimdi örneğimize geçerek .net core apimize swagger dökümanı eklemeye çalışalım.

Öncelikle Web Apimizden başlayalım. Motorcycle web api bize motorsiklet ekleme,silme,güncelleme ve listeleme gibi işlemler sağlayacak. Önce interfacemizi daha sonra servisimizi yazalım.

Servisimizi dependency injection için singleton olarak interface ile eşleştirerek, controllerımızı oluşturalım.

Evet şuan apimizi yazdık ben bir postman collection oluşturarak ilgili sorguları buraya kaydettim. Postman üzerindeki enviroment variable kısmını kullanarak da baseurlimi belirttim.

Image for post
Image for post

Fakat farkettiyseniz apimiz ayağa kalktığında bizi karşılayan, bize bilgi veren herhangi bir ui bulunmuyor. Şimdi bu problemi çözmek için yazının asıl amacı swagger entegrasyouna geçelim.

Öncelikle Swashbuckle.AspNetCore nuget paketini indirelim .

Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4

(Diğer Versionlar .net core 3.0 için şuanda sorun çıkartıyor.)

Şimdi Startup sınıfnımızı swagger kullanmak için düzenleyelim.

Swagger dokümanımızı daha detaylı hale getirmek için xml yorumları kullanacağız. Bunu aktif etmek için projemize sağ tıklayalım ve edit seçeneğini seçerek aşağıdaki konfigürasyonu ekleyelim.

<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Startup sınıfımızda SwaggerDoc bloğu altına XML yorumlarımızı kullanmak için

// Set the comments path for the Swagger JSON and UI.
var xmlFile = $”{Assembly.GetExecutingAssembly().GetName().Name}.xml”;
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

ilgili kod bloğunu ekleyelim. Daha sonra metotlarımızın başına “///” koyarak aşağıda ki örnekte olduğu gibi vermek istediğimiz bilgileri yazalım.

Uygulamayı çalıştırarak swagger dokümantasyonunun tadını çıkaralım. 😀

Evet arkadaşlar başarılı bir şekilde .Net Core 3.0 ile yazılan web apimize swagger dökümantasyonu ekledik. Umarım faydalı olmuştur.

Proje Linki : https://github.com/EnesAys/NetCoreApiandSwagger

Kaynaklar

https://docs.microsoft.com/tr-tr/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.0&tabs=visual-studio

Software Developer at Sosyopix

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store