Web API geliştirme aşamasında en elzem gereksinimlerden biri dokümantasyon gereksinimi olarak ifade edilebilir. Çünkü API yöntemlerinin ne işe yaradığı ya da ne şekilde kullanıldığı dokümantasyon sınırları içerisinde anlaşılır olması lazım. Api dokümantasyonunu elle yazmak ise hem zor hem de bu dokümantasyonu güncel bir şekilde tutmak için son derece zor. Bir şekilde bu dokümantasyonun güncelliğinin korunması ve üretimin devamı gerekiyor. İşte tam da bu noktada swagger bir kurtarıcı gibi koşuyor ve sorunlu olan duruma bir çözüm ışığı oluyor. Swagger’ın başka bir önemli bir amacı ise RestApiler için bir ara yüz sağlaması. Bu sayede insanların ve bilgisayarların kaynak koda ulaşma zorluğunu yaşamadan RestApilerin özelliklerinin gözükmesinin incelemesinin ve anlaşılmasının koşulları sağlanmış oluyor.
Swagger’ın Gradle için projeye dahil edilebilmesi amacıyla build.gradle dosyası konumuna dependency olacak şekilde eklenmesi gerekiyor. Ayrıca Swagger’ın Maven da projeye katılabilmesi amacıyla ise pom.xml dosyası konumuna yeniden dependency olarak eklenmesi son derece önemli.
Swagger’ın projeye dahil edildikten sonra bazı konfigürasyon işlemlerinin gerçekleştirilmesi gerekiyor. @Configuration olduğunun belirtilmesinden sonra @EnableSwagger2 aracılığıyla Swagger 2.0 spesifikasyonu aktif duruma getiriliyor. DocumentationType.SWAGGER_2 ile Swagger 2 kullanılacağı belirtiliyor burayı 1.2 veya WEB ile değiştirmek mümkün select() ile de ApiSelectorBuilder instance’sin döndürülme işlemi yapılıyor ve ayarlar bu işlemden sonra yapılıyor, apis() ile dokümana katılacak olan paketler seçilebiliyor, şu an içerisinde bütün paketler dahil olmak üzere isteğe bağlı olarak bunu değiştirerek belirlenen paketlerin kullanımı olağan, paths() ise bu durumlara benziyor. Yine aynı tarzda dokümana katılma durumu adreslerin belirlendiği konumda bulunuyor. Son aşamada yapılan proje olgunlaşmış oluyor {{adres}}/swagger-ui.html adresine gidilerek swagger aracılığıyla meydana getirilmiş olan dokümantasyona ulaşabiliyor. Bu işlemlerin olası yanlışlığında işlemler başarısız oluyor ve bu işlemleri doğru bir şekilde yapmak gerekiyor. Bu yüzden zaman kaybı da yaşamamak için işlemlerin yapılışının dikkatli bir şekilde sürdürülmesi son derece önem arz ediyor.
API’ler kullanılmak amacıyla (consume) tasarlandığı için tüketicilerin API’nizi hızlı bir biçimde uygulayabilmesini ve anlaşılmasını sağlamak son derece önemli bir nokta. Bu nedenle ki api dokümantasyonu olmazsa olmaz bir konumda bulunuyor. Dokümantasyon hazırlamak da çoğu insana göre bir işkence gibi geliyor. Ek olarak düşünelim ki zoru zoruna bir doküman oluşturuldu güncelliğini koruyup okunabilirliğini muhafaza etmek de aynı derece zor.
Tüketici konumunda yer alan bir insan dokümana baktığı zaman “Tanımı nedir, bu servis ne iş yapar, içerisinde ne tür operasyonları barındırıyor, bu operasyonların kullanım biçimi hangi tarzda olmalı, giriş çıkış parametreleri hangi türde?” benzeri soruların kolay bir şekilde cevaplanması akıllarda şüphe bırakmaması gerekiyor. Rest API uygulamaları yazılırken kaç tane endpointine bağlı olduğu, hangi endpointin görev konumu hangi endpointe nasıl istek atılacağını belirlemek amacıyla geleneksel usul olarak her şeyi otomatik olarak değil elle yazarak bir dokümantasyon oluşturulmalı.
Bu şekilde API'yi kullanalar hangi iş için neyi nasıl kullandığını kullanacağını öğrensin ve kavrasın. Eğer geleneksel usul takip edilmek istenmiyorsa biraz daha otomatik tarzda, yani biraz daha basit ve çok yönlü bir dokümantasyon yapılmak istenirse ortaya başka bir swagger çıkıyor. Bu başka olarak nitelendirilen swagger sadece dokümantasyon amacıyla kullanılmıyor. Rest API client kodununda üretimi yapılıyor. Oradan hareketle direkt istek gönderilip sonuçlara ulaşılabiliyor. Postman tarzı bir uygulama kullanılmadan da yapılan iş çözüme kavuşabiliyor.
Örnek olacak Projeye swagger eklemek amacıyla ilk olarak open source olarak geliştirilen Swashbuckle ismindeki kütüphaneyi proje sınırları dahilinde Nuget Package Manager Console kullanarak indirip kurma işlemi yapılacak. Kurulum işlemleri sonra erdikten sonra solution içerisinde yer alan ve App_Start klasörü açılarak bunun içerisine swagger configuration işlemleri yapmak amacıyla SwaggerConfig.cs isminde bir class eklendiği görülüyor. SwaggerConfig.cs içerisi default olarak aşağıda yer aldığı gibi gözükebilir.
Proje run edildiği zaman browser vasıtasıyla Swagger Ui sayfasına doğru {IIS de ki uygulama ismi}/swagger tarzında ulaşılabilir ve sayfa default olarak da aşağıda yer aldığı gibi gözüküyor.
Yukarıda da yer aldığı gibi gibi projede controller'lar sınırları dahilinde tanımlı olarak yer alan end-point'ler, Http Request çeşitleri, almış oldukları parametreler vs benzeri bilgiler de yer alıyor. Örnek vermek gerekirse POST /api/Values metodu bu noktada örnek olarak verilebilir. Metot adının üzerine tıklandığı zaman alt kısımda bir view expand oluyor ve bu noktada request olacak şekilde gönderilecek olan parametreler yazılıp response olarak alınabiliyor.
Yukarıda yer alan ekran görüntüsünde bulunan kısaca Values metodu string tarzda bir parametre alıyor. Sonrasında da geriye string bir response olarak dönüyor. Request parametresi yazıldıktan hemen sonra Try it out butonuna tıklandığı zaman da aşağıda yer alan bir ekran ile karşılaşmak son derece mümkün. Bu mümkün olan durum aşağıda görüldüğü üzere görsel olarak incelenebilir.
Bu durumdan yararlanan ve bu duruma kafa yoran yazılımcılar için sıkıntı haline gelen request response örnek kodları ifade etme doküman vs benzeri konuları da swagger vasıtasıyla bilhassa kolay ve çok yönlü bir hale getirmek mümkün. Swagger ile alakalı da daha birden çok configuration bulunuyor. VS üzerinden XML dosya generate edilerek kodların üstünde yer alan yorumlar izleyip yol edinip api dokümanı oluşturmak gibi birden çok mahareti bulunuyor. Detaylı bilgi için de Swagger.io Swashbuckle ile alakalı güncel ve daha detaylı bilgiler için hep bir takipte bulunmak son derece önemli. Yukarıda kolay tarzıyla swagger anlatıldı fakat en başta da belirtildiği gibi swagger.config dosyasını düzgün yorumlayabilme becerisini kazandıktan sonra daha birçok özellik bu vasıtayla bulunabilir.
Swagger yazılımlar için çokça kullanılan ve bu uğurda bir bilgi birikimi gerektiren bir konumda bulunuyor. Web API değiştirip geliştirme noktasında yer alan en önemli ihtiyaçlardan biri dokümantasyon gereksinimi olacak şekilde açıklanıyor olmasının en büyük sebebi de öneminden kaynaklanıyor. Projeye dahil edilen swaggerin bazı konfigürasyon işlemlerinin yapılmasının gerçekleştirilmesi son derece beklenen ve önemsenen bir durum. Bu yüzden bu adımlar dikkatli bir şekilde doğruca uygulanıp kavranmalı. Swagger.config dosyasının doğru bir şekilde değerlendirilip doğru çıkarımının yapıldığı zaman bu becerinin aracılığıyla birçok özellikten ve katkıdan yararlanılabileceğin bilinmesi önemli.
Swagger’ın Gradle için projeye dahil edilebilmesi amacıyla build.gradle dosyası konumuna dependency olacak şekilde eklenmesi gerekiyor. Ayrıca Swagger’ın Maven da projeye katılabilmesi amacıyla ise pom.xml dosyası konumuna yeniden dependency olarak eklenmesi son derece önemli.
Swagger’ın projeye dahil edildikten sonra bazı konfigürasyon işlemlerinin gerçekleştirilmesi gerekiyor. @Configuration olduğunun belirtilmesinden sonra @EnableSwagger2 aracılığıyla Swagger 2.0 spesifikasyonu aktif duruma getiriliyor. DocumentationType.SWAGGER_2 ile Swagger 2 kullanılacağı belirtiliyor burayı 1.2 veya WEB ile değiştirmek mümkün select() ile de ApiSelectorBuilder instance’sin döndürülme işlemi yapılıyor ve ayarlar bu işlemden sonra yapılıyor, apis() ile dokümana katılacak olan paketler seçilebiliyor, şu an içerisinde bütün paketler dahil olmak üzere isteğe bağlı olarak bunu değiştirerek belirlenen paketlerin kullanımı olağan, paths() ise bu durumlara benziyor. Yine aynı tarzda dokümana katılma durumu adreslerin belirlendiği konumda bulunuyor. Son aşamada yapılan proje olgunlaşmış oluyor {{adres}}/swagger-ui.html adresine gidilerek swagger aracılığıyla meydana getirilmiş olan dokümantasyona ulaşabiliyor. Bu işlemlerin olası yanlışlığında işlemler başarısız oluyor ve bu işlemleri doğru bir şekilde yapmak gerekiyor. Bu yüzden zaman kaybı da yaşamamak için işlemlerin yapılışının dikkatli bir şekilde sürdürülmesi son derece önem arz ediyor.
API’ler kullanılmak amacıyla (consume) tasarlandığı için tüketicilerin API’nizi hızlı bir biçimde uygulayabilmesini ve anlaşılmasını sağlamak son derece önemli bir nokta. Bu nedenle ki api dokümantasyonu olmazsa olmaz bir konumda bulunuyor. Dokümantasyon hazırlamak da çoğu insana göre bir işkence gibi geliyor. Ek olarak düşünelim ki zoru zoruna bir doküman oluşturuldu güncelliğini koruyup okunabilirliğini muhafaza etmek de aynı derece zor.
Tüketici konumunda yer alan bir insan dokümana baktığı zaman “Tanımı nedir, bu servis ne iş yapar, içerisinde ne tür operasyonları barındırıyor, bu operasyonların kullanım biçimi hangi tarzda olmalı, giriş çıkış parametreleri hangi türde?” benzeri soruların kolay bir şekilde cevaplanması akıllarda şüphe bırakmaması gerekiyor. Rest API uygulamaları yazılırken kaç tane endpointine bağlı olduğu, hangi endpointin görev konumu hangi endpointe nasıl istek atılacağını belirlemek amacıyla geleneksel usul olarak her şeyi otomatik olarak değil elle yazarak bir dokümantasyon oluşturulmalı.
Bu şekilde API'yi kullanalar hangi iş için neyi nasıl kullandığını kullanacağını öğrensin ve kavrasın. Eğer geleneksel usul takip edilmek istenmiyorsa biraz daha otomatik tarzda, yani biraz daha basit ve çok yönlü bir dokümantasyon yapılmak istenirse ortaya başka bir swagger çıkıyor. Bu başka olarak nitelendirilen swagger sadece dokümantasyon amacıyla kullanılmıyor. Rest API client kodununda üretimi yapılıyor. Oradan hareketle direkt istek gönderilip sonuçlara ulaşılabiliyor. Postman tarzı bir uygulama kullanılmadan da yapılan iş çözüme kavuşabiliyor.
Örnek olacak Projeye swagger eklemek amacıyla ilk olarak open source olarak geliştirilen Swashbuckle ismindeki kütüphaneyi proje sınırları dahilinde Nuget Package Manager Console kullanarak indirip kurma işlemi yapılacak. Kurulum işlemleri sonra erdikten sonra solution içerisinde yer alan ve App_Start klasörü açılarak bunun içerisine swagger configuration işlemleri yapmak amacıyla SwaggerConfig.cs isminde bir class eklendiği görülüyor. SwaggerConfig.cs içerisi default olarak aşağıda yer aldığı gibi gözükebilir.
Proje run edildiği zaman browser vasıtasıyla Swagger Ui sayfasına doğru {IIS de ki uygulama ismi}/swagger tarzında ulaşılabilir ve sayfa default olarak da aşağıda yer aldığı gibi gözüküyor.
Yukarıda da yer aldığı gibi gibi projede controller'lar sınırları dahilinde tanımlı olarak yer alan end-point'ler, Http Request çeşitleri, almış oldukları parametreler vs benzeri bilgiler de yer alıyor. Örnek vermek gerekirse POST /api/Values metodu bu noktada örnek olarak verilebilir. Metot adının üzerine tıklandığı zaman alt kısımda bir view expand oluyor ve bu noktada request olacak şekilde gönderilecek olan parametreler yazılıp response olarak alınabiliyor.
Yukarıda yer alan ekran görüntüsünde bulunan kısaca Values metodu string tarzda bir parametre alıyor. Sonrasında da geriye string bir response olarak dönüyor. Request parametresi yazıldıktan hemen sonra Try it out butonuna tıklandığı zaman da aşağıda yer alan bir ekran ile karşılaşmak son derece mümkün. Bu mümkün olan durum aşağıda görüldüğü üzere görsel olarak incelenebilir.
Bu durumdan yararlanan ve bu duruma kafa yoran yazılımcılar için sıkıntı haline gelen request response örnek kodları ifade etme doküman vs benzeri konuları da swagger vasıtasıyla bilhassa kolay ve çok yönlü bir hale getirmek mümkün. Swagger ile alakalı da daha birden çok configuration bulunuyor. VS üzerinden XML dosya generate edilerek kodların üstünde yer alan yorumlar izleyip yol edinip api dokümanı oluşturmak gibi birden çok mahareti bulunuyor. Detaylı bilgi için de Swagger.io Swashbuckle ile alakalı güncel ve daha detaylı bilgiler için hep bir takipte bulunmak son derece önemli. Yukarıda kolay tarzıyla swagger anlatıldı fakat en başta da belirtildiği gibi swagger.config dosyasını düzgün yorumlayabilme becerisini kazandıktan sonra daha birçok özellik bu vasıtayla bulunabilir.
Swagger yazılımlar için çokça kullanılan ve bu uğurda bir bilgi birikimi gerektiren bir konumda bulunuyor. Web API değiştirip geliştirme noktasında yer alan en önemli ihtiyaçlardan biri dokümantasyon gereksinimi olacak şekilde açıklanıyor olmasının en büyük sebebi de öneminden kaynaklanıyor. Projeye dahil edilen swaggerin bazı konfigürasyon işlemlerinin yapılmasının gerçekleştirilmesi son derece beklenen ve önemsenen bir durum. Bu yüzden bu adımlar dikkatli bir şekilde doğruca uygulanıp kavranmalı. Swagger.config dosyasının doğru bir şekilde değerlendirilip doğru çıkarımının yapıldığı zaman bu becerinin aracılığıyla birçok özellikten ve katkıdan yararlanılabileceğin bilinmesi önemli.
