Swagger ve Java ile Restful API Dokümantasyonu

API’lerimizin Kullanma Kılavuzları olan Swagger

Öncelikle herkese merhabalar! bugün bir projenin geliştirilmesinin, yönetilmesinin ve sürdürülebilmesinin en etkili rollerinden birisi olan dokümantasyonlama kısmının, Rest API (Endpoint) lerimiz üzerinde ki kullanımını öğreneceğiz.

Ne izah etmek istiyorum ? Örneğin bir method oluşturdunuz ve Frontend den buraya bir istek gelecek, ya da Dışarıya bir API servisi açtınız her ne olursa olsun neticede o endpoint in Nasıl kullanılacağını, response olarak muhtemel ne alacağınızı, gerekli parametreleri ve onların tiplerini ayrıca gönderilmesi zorunlu olup olmadığı bilgisini dahi dokümanlaştırdığınız bir araç olan Swagger ‘ı anlatacağım.

bu yazımızda baştan sona neleri işleyeceğimizi, hangi section da hangi özelliklerini anlatacağımı aşağıdaki Bağlantılardan direkt olarak yazının o kısmına ulaşabilirsiniz.

Makalenin İçeriği :

• Swagger Nedir ?
• Swagger dependency eklenmesi
• Swagger Configuration ile projeye dahil edilmesi
• Customize Edilmesi
• Controller Seviyesinde dokümanlaştırılması (Methodları)
• Endpoint Seviyesinde dokümanlaştırılması (Methodları)
• Field Seviyesinde dokümanlaştırılması (Methodları)
• Endpoint ’in Swagger da gizlenmesi
• Production Ortamında Gizlenmesi
• Swagger ‘ı amacı doğrultusunda kullanmak

Swagger Nedir

bu section yukarıda açıkça ifade edildiğinden dolayı aynı cümleleri tekrarlamaya gerek duymuyorum. En basit tanımı ile dış departmanlara (Mobil, Web, Etc.) açtığımız endpointleri veya diğer adıyla Restful API lerimizin nasıl kullanılması hakkında direktif ve yönergeleri içeren dokümantasyon oluşturma aracıdır.

Aşağıda ki Görsellerde Swagger Arayüzünü Görüyorsunuz. Dependency eklenmesinden, makalenin sonuna kadar teker teker öğrendiğimiz her şeyi uyguladığımızda tam olarak aşağıdaki gibi bir görüntü elde edeceğiz.

swagger ui

endpoint document

Swagger dependency eklenmesi

Swagger aracını projemizde kullanabilmemiz için ilk adım maven repository den gerekli kütüphaneyi projemize dahil etmek olmalı. Bunun için java da paket yönetimimi sağladım pom.xml dosyama aşağıda gördüğünüz bağımlılığı ekliyorum.

36 ile 40. satırlar arasında ki dependency benim ihtiyacım olan bağımlılık. Bu yazıyı yazmamda ki en büyük sebeb, swagger 3 ile beraber core code ve ui dependency lerinin bir pakette birleşmiş olduğunu göstermek. Uzun lafın kısası bu bağımlılığı kütüphanemize ekleyelim.

Swagger Configuration ile projeye dahil edilmesi

Bu noktada artık java projeme Swagger aracını tanıtmam gerekiyor, hangi ayarlarda çalışacağını belirtmem gerekiyor. Neticede bu araç endpointleri ve requestleri handle edeceği için bu yolları path leri swagger a söylemem gerekiyor.

Öncelikle config klasörüm altında SwaggerConfig.java isimli config sınıfımı oluşturup aşağıda ki gibi configure ediyorum.

EnableSwagger2 ile context e dahil ediyorum

RequestHandlerSelectors ile Request objelerimin path ’ini tanıtıyorum

PathSelectors ile de hangi endpoint ’leri dinleyeceğini belirtiyorum. ben hepsini dinlemesini istediğim için /.* regex pattern ’ını kullandım, eğer sadece /home altını dokümanlaştırmak isteseydim /home kullanacaktım.

Customize Edilmesi

Ama fark ettiyseniz hala görselde ki gibi değil di mi ? mesela bu dokümantasyonun yazarı, auditor ‘ı etc. gibi bilgileri de dahil etmek istiyorum. O halde build ederken şu şekilde bir api info veriyorum

Controller Seviyesinde dokümanlaştırılması (Methodları)

Bu noktadan sonra ki anlatımları genelde kod üzerinden ilerleticem.

Api Endpoint ’i ile Controller ‘ıma bir değer veriyorum, bunu yaparak aşağıda gördüğünüz görüntüyü elde ettim.

Ek Bilgi : @Api annotation kullanımı zorunlu değildir. Eğer kullanmasaydım Login Controller yerine login-controller-ımpl yazacaktı.

Endpoint Seviyesinde dokümanlaştırılması (Methodları)

örnek

yukarı da görselde görüldüğü üzere @ApiOperation isimli annotation ile swagger arayüzüme daha anlaşılır ve açıklayıcı yönergeler yerleştirdim. şimdi bu değerlerin arayüze nasıl yansıdığını görelim.

notes : bu kısımda belirttiğim metin, description olarak değerlendirebiliriz, bu api yi kullanacak olan Developer’a bu endpoint ‘in ne işe yaradığını açıkladığımız kısımdır.

value : bu description a kıyasla bir title olarak nitelendirebiliriz. Servis içinde hangi methoda erişeceğini belirttiğimiz alan.

Ek Bilgi : @ApiOperation annotation içine girerek bir çok özelliğini kendiniz direkt deneyimleyebilirsiniz. Ben örnek açısından 2 tanesinden bahsettim.

Field Seviyesinde dokümanlaştırılması (Methodları)

Yukarı da ise bu endpoint ‘in kullanım aşamasında kullanıcısından gerekli backend sunucumuza gönderilmesi gereken Request Objesinden Zorunlu olanları işaretlediğim kısım. Ben bu örnekte @ApiParam ile arayüze bunun gönderilmesinin zorunlu olduğunu belirtiyorum. Arayüzde ise şu şekilde görünüyor.

required : zorunlu olduğunu belirtiyor.

value : parametrenin description kısmını belirtiyor.

example : hint/placeholder kısmı için kullanılıyor

Ek bilgi: @CustomConstraint annotation kullanımına dikkat etmeyin, eğer incelemek isterseniz, Buradan o yazıma da ulaşabilirsiniz.

Ek Bilgi: @NotBlank ve @NotNull annotation kullandığınız taktirde swagger da otomatik olarak required bilgisi oluşacaktır. required = true zorunlu kılınmaz bu durumda

Endpoint ‘in Swagger da gizlenmesi

Bazen bir endpoint ‘iniz kritik olabilir, örneğin ödeme, gizlilik veya implemente edilmemesi gereken, ama endpoint’ in var olması gereken durumlar gibi. Tam bu noktada görselde göreceğiniz şekilde, bu endpoint’i swagger da gizleyebilirsiniz.

hidden=true

hidden = true ile gizlenebildiği gibi , @ApiIgnore da kullanılabilir, ancak fazladan annotation tanımlamamak için hidden’ ı tercih ediyorum.

Production Ortamında Gizlenmesi

Swagger sadece Development aşamasında bir anlam taşıdığı için, gerek güvenlik gerekse de başka sebeblerden bunu gizlemek isteyebilirsiniz.

Swagger 3 ile gelen en güzel özelliklerden birini göreceğiz ama öncesinde 3 altı versiyonlarda bunun nasıl olduğuna bakalım.

Görselden de anlaşılacağı üzere @Profile annotation ile çalışma profili dev ise sadece config oluşacaktır. Ama ben bu kontrolü uygun bulmuyorum.

Güncel kullanım ise şöyledir:

springfox.documentation.enabled: false

bu satırı, application-prod.yml ye eklerseniz, prod ortamında swagger devre dışı kalacaktır.

Swagger ‘ı amacı doğrultusunda kullanmak

Üzülerek söylemeliyim ki ekosistemde ki çoğu geliştirici swagger ‘ı bir API test aracı zannederek kullanıyor. Postman ‘e kıyasla daha kolay olduğu için tercih edilmesi mantıklı geliyor. Fakat Değil !

Swagger bir API dokümantasyon aracıdır, Postman ise API Test aracıdır.

swagger ile istek atılabilir mi ? elbette atılır, ama düşünün ki siz request’in header kısmında bir signature istiyorsunuz… bu durumda bu api yi swagger dan test edemezsiniz, ya da execution time’ı incelemek ya da direkt olarak PROD adresine istek atmak istiyorsunuz, ama prod da gizledik ? bunun gibi onlarca senaryo üretilebilir. Her Aracı doğasına uygun kullanarak Single Responsibility Principle ilkesini benimseyelim.

Makalenin sonuna kadar geldiğiniz için teşekkür ederim, umarım bu yazı faydalı olmuştur size, başka yazılarda görüşmek üzere iyi çalışmalar !