Giriş
Hayatınızda hiç ASP.NET Web API projesi yaptınız mı? Yaptıysanız eğer en azından bir kere bu API’ı kullanacak istemci (client) için de bir kütüphane yazmışsınızdır. Sonrasında ya bunun daha iyi bir yolu olması lazım diye kendi kendinize düşünmüşsünüzdür ya da Swashbuckle’ı duymuşsunuzdur.
Swagger ve Swashbuckle
Swashbuckle’ın ne yaptığını sorarsak, kendisinin Swagger tanımı oluşturan bir kütüphane olduğunu söyleyebiliriz. Tabii öncesinde Swagger ve tanımının ne olduğunu bilmemiz gerekiyor.
Swagger, bir API’ın bütün hayat döngüsü içerisinde kullanılabilecek araçları kapsamaya çalışan bir kütüphanedir. Spesifikasyonun adı 3.0 versiyonu ile birlikte OpenAPI olarak değiştirildi ve artık ekosistemde bir standart oldu.
Swagger tanımı aslında API’ınızın içerisinde hangi uçnoktaların (endpoint) olduğunu, o endpointlerden alınabilecek cevapların neler olduğunu ve cevabın bir modeli varsa bu modelin ne olacağını belirten bir döküman. Bu döküman ve Swagger içerisinde bulunan araçlar sayesinde, API tanımına uygun bir sunucu (server) ve ya istemci oluşturulabiliyor. Aynı zamanda bu araçların içerisinde size bu API’a istek yapabilmenizi sağlayan bir kullanıcı arayüzü de var.
Swashbuckle ise sizin oluşturduğunuz ASP.NET Web API projesi içerisinde olan Controller sınıfları üzerinden bu Swagger tanımını oluşturabiliyor. Aynı zamanda API’ınızı kullanabileceğiniz Swagger UI arayüzünü de ekleyebiliyor. Böylece siz yazdığınız server tarafındaki endpointleri kullanabilecek client projesini Swagger tanımı aracılığıyla otomatik olarak oluşturabiliyorsunuz. Swagger Editor size bu konuda yardımcı olacaktır.
Kodu Görelim
Bu örnekte, herhangi bir yerden veri çekme ile uğraşmayalım diye bir kategori listesi üreteceğiz ve bu kategorilere Id özellikleri ile birlikte tekil olarak erişebileceğiz.
Öncelikle boş bir Web API projesi oluşturuyoruz.
Proje içerisine, NuGet içerisinden Swashbuckle’ı bulup referans ediyoruz.
Models klasörünün içerisine aşağıdaki “Category” sınıfını ekliyoruz.
https://gist.github.com/fatihdgn/0f19875969487b341a5517547b6350c0
Sonrasında ise Providers adında bir klasör oluşturuyoruz ve içerisine aşağıdaki “CategoryProvider” sınıfını ekliyoruz. Bu sınıf ile birlikte, uygulama başlatıldığında random üretilmiş beş adet kategoriye sahip olacağız.
https://gist.github.com/fatihdgn/f5e9b5b26d0363829632ff49d9a8bad6
Son adım olarak Controllers klasörünün içerisine “CategoryController” ekliyoruz.
https://gist.github.com/fatihdgn/94f8bfd157aa07193e02a95d696a4b3d
Sonuç olarak aşağıdaki ekran görüntüsüne benzer bir ekran elde etmiş olmanız gerek.
Ve web projenizi başlatın. /swagger adresine gittiğinizde Swagger UI paneli ile karşılaşacaksınız.
Üst menüde, API’ınızın Swagger dökümanına ulaşabileceğiniz bir adres bulunuyor. Bu döküman sayesinde uygulamanıza istek yapabileceğiniz bir istemci oluşturabilirsiniz.
Aynı zamanda aşağıda, biraz önce eklediğimiz “CategoryController” içerisindeki iki endpoint bulunuyor. Arkada oluşturduğumuz kategori listesini almak için, “/api/Category” üzerine tıklayıp, aşağıda beliren “Try it out!” butonuna tıklayın.
Bunun sonucunda, hemen aşağıda kategorilerinizin bir listesini görebilirsiniz.
Arasından herhangi birinin Id özelliğini kopyalayıp, “/api/Category/{id}” tabında aynı adımları izleyerek, spesifik bir kategoriyi getirme isteğini de yapabilirsiniz.
Bugün, Swashbuckle ve Swagger’ı tanımladık, inceledik. Umarım keyifli ve öğretici bir yazı olmuştur. Bir sonraki yazıda görüşmek üzere.