Visual Studio bizim için varsayılan bir web api projesi oluşturdu. Solution Explorer dan controllerlarımızın olduğu Controllers klasörüne baktığımız zaman 2 adet (HomeController.cs ve ValuesController.cs) controller olduğunu görüyoruz.
Bunlardan ValuesController sınıfını açtığımız zaman sınıfımızın ApiController isimli classdan inherit ettiğini görüyoruz.
public class ValuesController : ApiController
{
// GET api/values
public IEnumerable Get()
{
return new string[] { "value1", "value2" };
}
// GET api/values/5
public string Get(int id)
{
return "value";
}
// POST api/values
public void Post([FromBody]string value)
{
}
// PUT api/values/5
public void Put(int id, [FromBody]string value)
{
}
// DELETE api/values/5
public void Delete(int id)
{
}
}
Bunun anlamı ValuesController sınıfı web apimiz için metodlar yazacağımız sınıfımız olduğu(Eğer istersek kendimiz controller oluşturup ApiController sınıfından inherit etmesini sağlayabilirdik).
Dikkat edersek metodların üzerinde yorum satırları olduğunu görürüz. İşte Swaggerın bize sunacağı dökümantasyon kütüphanesi bu yorum satırlarından oluşuyor.
Projemize swagger kütüphanesini nuget paket yöneticisini kullanarak ekleyebiliriz. Öncelikle nuget package manager consoluna Install-Package Swagger.Net yazalım ve Swagger.Net in kütüphanesini projemize ekleyelim.
Artık ValuesController sınıfımızda web api metodlarımızın üzerine yazdığımız yorum satırlarına swaggerın sunduğu api üzerinden erişebiliriz. Ama önce projemizi derleyip çalıştıralım. Aşağıdaki hata ile karşılaşmamız normal çünkü gereken bazı ayarları yapmadık.
Hatada da yazdığı gibi swaggerın çalışabilmesi için projemize sağ tıklayıp Properties >Build ‘ e geliyoruz .
Buradan XML documentation file seçeneğini işaretliyoruz(varsayılan olarak işaretsiz geliyor) ve dökümantasyon dosyamızın nereye kaydedileceğini seçiyoruz. Default değerde bırakıyoruz( Eğer custom bir yol belirlemişsek çalışmayacak. Çalışması için AppStart/SwaggerNet.cs dosyasını düzenlememiz gerekiyor)
Şimdi projemizi derleyip çalıştıralım ve Url adresine http://localhost:xxxxx/api/swagger girelim. Karşımıza json formatında bazı bilgiler çıkacaktır.
Aslında bu gördüğümüz bilgiler Swagger kütüphanesinin bize sunduğu dökümantasyon bilgilerimiz. Ama dikkat edersek description kısmında ” No Documentation Found” diyor. Yani dökümantasyon bulunamadı. Bunun sebebi swaggerın metodun üzerine yazdığınız dökümantasyon commentlerinin formatını öyle kafanıza göre veremiyor olmanız. Yazılım dünyasında genel olarak kabul gören dökümantasyon formatlarını kullanmalısınız ki swagger bunu net birşekilde algılayıp parametre yollamanıza olanak sağlasın(Parametre olayı ileride işlenecek). O zaman biraz dökümantasyon yapalım.
/// /// Get all of the values. ////// public IEnumerable Get() { return new string[] { “value1”, “value2” }; } ///
/// Get a single Value by it’s id ////// /// public string Get(int id) { return “value”; } ///
/// Post api/values ////// /// public void Post([FromBody]string value) { } ///
/// Put api/values ////// /// /// public void Put(int id, [FromBody]string value) { } ///
/// Remove a Value by it’s id ////// public void Delete(int id) { }
Metodlarımızı dökümante ettikten sonra swagger apisini çağırdığımızda bize vereceği veri aşağıdaki gibi oluyor.
{“apiVersion”:”4.0.0.0″,”swaggerVersion”:”2.0″,”basePath”:”http://localhost:59501″,”resourcePath”:null,”apis”:[{“path”:”/api/docs/Values”,”description”:”Get all of the values.”,”operations”:[]}]}
Şimdi ikinci kullanacağımız araç swagger-ui . Bu kütüphane swagger apide bize dönen değerleri güzel bir arayüzde bize sunup dökümante ettiğimiz metodları test edebilmemize ve dökümanteyi görebilmemize olanak sağlayan bir UI. Bunuda Nuget yardımıyla projemize ekliyoruz. Package Manager Consolumuza Install-Package Swagger.Net.UI yazıyoruz ve enter a basıyoruz. Gerisini nuget halledecek ve projemize ekleyecektir.
Dikkat eder isek projemize SwaggerUi diye bir klasör ekledi. Bu klasörün içerisinde swagger apisinden dönen değerleri bize sunan arayüz, html ve js ler bunlunmakta.
Projemizi derleyip çalıştırıyoruz. Ve url adresimize http://localhost:xxxxx/swaggerui/ yazıyoruz. Karşımıza gelen ekran SwaggerUi ‘ın ana ekranı.
Burada dikkat edersek http://YOUR-URL-HERE:PORT/api/swagger diye bir url yazıyor. Bu url adresi bizim swagger apimizin url i (swagger ui kurmadan önce bize json formatında veri veren api).
Oraya kendi swagger apimizin adresini giriyoruz ve explorer butonuna basıyoruz.
Farkettiyseniz bizim Values isimli web apimiz geldi. Hemen üzerine tıklıyoruz.
Gördüğünüz gibi Values isimli web api sınıfımızın içindeki tüm metodlar ve dökümantemiz geldi.(Yorumlarımız sağda gözüküyor). Şimdi ilk olarak /api/Values isimli metodumuzu temsil eden get metodumuza tıklayalım.
Try it out isimli buton karşımıza geldi. Tıklayalım.
Evet metodumuz çalıştı ve veriyi json formatında gönderdi. Bu şekilde restfull metodlarınıda SwaggerUi üzerinden test edebiliyoruz. Peki ya parametre göndermek istersek o zaman nasıl yapacağız? Aşağıdaki gibi…
Örnek Projenin Github Adresi:https://github.com/fuattatar/swaggernet.git
Kaynak:
https://github.com/Swagger-Net/Swagger.Net
https://github.com/wordnik/swagger-spec
http://swagger.io/
https://www.nuget.org/packages/Swagger.Net.UI/
Fuat Tatar 