SpringFox ve Swagger ile API Dokümantasyonu — 1
Bir REST API oluştururken aynı zamanda iyi bir dokümantasyon da oluşturmamız gerekir. Bu iş çoğu yazılımcı için sıkıcı bir süreçken, proje gelişim aşamasında kodlarımızda ve dolayısıyla yazılmış dokümantasyonda da değişiklik yapmamız işi daha can sıkıcı hale getiriyor. Bu nedenle dokümantasyon işini otomatize edecek çeşitli araçları kullanmak kaçınılmaz oluyor.
SpringFox Swagger 2 spesifikasyonunu kullanarak otomatik olarak oluşturduğumuz dokümantasyon, request-response modelleri, test ekranı yanı sıra 3. parti uygulamalarda da kullanılabilecek, benim WSDL dosyalarına benzettiğim, projenin JSON formatında özetini barındırır. Bu JSON dosyası ile hiç bir ek geliştirme yapmadan - çaba harcamadan ister POSTMAN gibi test uygulamalarına uygulamayı test etmek için ekleyebilir, isterseniz API Spot gibi ek uygulamalarla proje haritanızı çıkartabilir ve test senaryoları yazabilirsiniz.
Swagger, OpenAPI Spesifikasyonu (OAPI) için dünyanın en geniş API geliştirme aracı araçlarından biridir. Tasarım ve dokümantasyondan, test ve dağıtıma kadar tüm API yaşam döngüsü boyunca daha az maliyetle geliştirme yapılmasına olanak tanır.
SpringFox ise Spring Framework için özelleştirilmiş özgür yazılım lisanslı bir projedir.
Springfox paketi, Spring projeleri kullanılarak yazılan JSON API’leri için makine ve insan tarafından okunabilir hale getirebilmek amacıyla sınıf yapısına ve çeşitli JAVA Annotations’larına dayanan ve uygulama derlenirken bir kez çalışan kütüphanedir.
Daha fazla uzatmadan SpringFox kullanımına geçelim.
SpringFox kütüphanesinin eklenmesi ile başlayalım. Swagger ile swagger-ui kurulumunu yapıyoruz. Swagger-ui hakkında çok açıklama yapmaya gerek yok, yazı içinde göreceğiniz ekran görüntüleri sadece aşağıda ekleyeceğimiz swagger-ui projesi ile hiç bir ayar yapmadan elde edilmiştir. {{adres}}/swagger-ui.html adresinden ulaşabilirsiniz
Gradle ile
Maven ile
Paketleri projemize ekledikten sonra SpringFox ayarlarının yapılması ile devam edebiliriz. Ben halihazırda çeşitli endpointlere sahip bir projemizin olduğunu varsayarak yazıya devam ediyorum. Zaten SpringFox uygulama kısmınıza müdahale etmenize gerek kalmadan sadece ayrı bir yapılandırma dosyası ile Swagger2 formatında JSON çıktınızı üretmenize olanak sağlayan bir proje. Bu nedenle sadece ayar sınıfımızı oluşturmamız bizim için yeterli.
@Configuration olduğunu belirttikten sonra @EnableSwagger2 ile Swagger 2.0 spesifikasyonunu aktif hale getiriyoruz. DocumentationType.SWAGGER_2 ile Swagger 2 kullanacağımızı belirtiyoruz, burayı 1.2 ya da WEB ile değiştirebilirsiniz. select() ile ApiSelectorBuilder instance’si döndürülüyor ve ayarlarımız bunun üzerine yapılıyor. apis() ile dokümana dahil edilecek paketleri seçebiliyoruz, şu an tüm paketler dahil ve bunun sonucunu ileride görüp bu alanı değiştirmemiz gerektiğini anlayacağız. paths() ise yine aynı şekilde dokümana dahil edilecek adreslerimizi belirlediğimiz yer, bu alanı regex gibi yöntemler ile özelleştirmenizi öneririm, ileride bununda örneğini göreceksiniz. Sadece bu kısım ile kullanabileceğimiz bir doküman ve aşağıdaki test ekranı elde ettik. Tekrar belirtiyorum aşağıdaki ekran için yukarıdaki ayar sınıfı dışında uygulamaya başka bir şey eklemiyoruz.
Yukarıda bir kaç satır JAVA kodu ile yukarıdaki ekranları elde ettik, aslında bu ekran {ana-adres}/v2/api-docs adresinde mevcut olan JSON çıktısından elde edildi, burada mevcut olan JSON ile POSTMAN gibi çeşitli uygulamaları kullanabilirsiniz.
Doküman dedik dedik test ekranı gibi bir şey elde ettik, dokümantasyon için belirli açıklamalar eklememiz gerekiyor. Bunun için servis — controller katmanında
İstek objelermizde ki alanlar için ise
Annotationları ile dokümanı zenginleştirebiliriz.
İlk ekran görüntüsünde gördüğünüz üzere person kontroller dışında çeşitli Spring’in kendine ait servisleri mevcut. Daha önce belirttiğim ve aşağıda eklediğim ayar değişikliği ile bu sorunu çözebiliriz.
Şimdi de dokümantasyon bilgilerini düzenlemeye bakalım. Yine aşağıdaki ekleme ile doküman sahibi, açıklama, lisans, versiyon ve iletişim bilgileri ekleyebiliriz. ApiInfo objesi api bilgilerini içeren objedir.
Bu yazımda SpringFox paketini projemize ekledik, basit ayarlarını yaptık, swagger-ui ile nasıl deneme istekleri gönderebileceğimizden bahsettik. Bundan sonraki yazılarda swagger-ui ile yetkilendirme işlemleri, ve doküman oluşturmaya değineceğim.
