Swagger Nedir ? Asp.Net Core 3.1 Web Api ile Kullanımı
Selamlar,
Bu yazımda Swagger nedir, neden kullanmalıyız ve projelerimize nasıl dahil ederiz bahsetmeye çalışacağım.
Swagger Nedir ?
Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.
Swagger, yazılım geliştiricilerin Restful api’lerini tasarlamasına, oluşturmasına, belgelemesine ve rahat bir şekilde kullanmasını sağlayan doküman oluşturma tool’u dur. Swagger, otomatik dokümantasyon ve test senaryosu ile birlikte yaygın bir şekilde kullanılmaktadır.
Neden Swagger Kullanmalıyız ?
API geliştirmede dokümantasyon önemli bir ihtiyaçtır. Yazmış olduğunuz servisleri kullanacak diğer geliştiricilere ya da herkese açık olarak paylaşmak istediğinizde, API metotlarınızın ne işe yaradığı, nasıl çalıştığı ile ilgili gerekli bilgiyi de paylaşmalısınız. Api dokümanınızın manuel olarak el ile yazmak hem büyük bir vakit kaybı hem güncel tutmanız imkansıza yakındır. Bu sorunlara çözüm olarak swagger işimizi büyük ölçüde hafifletmektedir.
Swagger, yazmış olduğumuz Rest Api’lerin incelenmesi, anlaşılması ve test edilmesini sağlayan bir arayüz sağlamaktadır. İsterseniz şimdi bir örnek ile nasıl projelerimize dahil edeceğimize geçelim.
Yapacağımız örnekte .Net Core 3.1 Web Api kullanılarak yapılmış olan bir projeye swagger ekleyeceğiz.
Öncelikle projemize Nuget Packages aracılığıyla Swashbuckle.AspNetCore kütüphanesini projemize dahil ediyoruz.
Ardından Startup.cs dosyasına ilgili ayarlamalarımızı yapıyoruz.
Startup.cs / ConfigureServices :
Startup.cs / Configure :
Burada dikkat etmemiz gereken en önemli nokta ConfigureServices içerisinde tanımlamış olduğumuz SwaggerDoc “v1” parametresi ile Configure içerisindeki SwaggerEndpoint “v1” aynı ada sahip olmalıdırlar.
Uygulamayı çalıştırıp url’in sonuna /index.html yazarak swagger’in oluşturmuş olduğu dokümanı görüntüleyebiliriz.
Swagger üzerinde Api’lerimizi çalıştırmak için ;
Buna ek olarak geliştirme yaparken bitmemiş olan veya dokümanda bulunmasını istemediğiniz metotlar için metodun başına [ApiExplorerSettings(IgnoreApi = true)] eklemeniz gerekmektedir.
Client tarafından istek yapılırken farklı yollar ile bilgileri aktarabilirler. Bunlardan biride header ile yapılmaktadır. Metotlarınıza header ile gelen bilgi varsa ve bunuda swagger ui üzerinde test etmek isterseniz aşağıdaki kodu projenize eklemeniz yeterli olacaktır.
Yukarıdaki metodu Startup / ConfigureServices içerisinde tanımlamamız gerekir. Son durumda aşağıdaki gibi olacaktır.
Bu yazımda Swagger nedir, projeye nasıl dahil edilir genel hatlarıyla anlatmaya çalıştım. Umarım faydalı olur.
Görüşmek dileği ile ..
