Spring Boot ile Swagger Kullanımı
Herkese merhaba, ben Sümeyye. Bu haftaki yazımda sizlerle swagger hakkında konuşacağız ve ardından spring boot ile örnek bir proje gerçekleştireceğiz.
Öncelikle hep birlikte swagger’ın ne olduğuna bakalım.
Swagger Nedir?
Web API geliştirmede en önemli ihtiyaçlardan biri dokümantasyon ihtiyacıdır. Çünkü API metodlarının ne işe yaradığı ve nasıl kullanıldığı dokümantasyon içeresinde anlaşılır olması gerekir. Bunun nedeni ise oluşturulan API’ lerin okunurluğu ne kadar fazla olursa API’yi kullanacak ekiplerin anlaması o kadar kolay olabilir.
Swagger bir çok dili desteklemektedir. Spring Boot ile kullanmamız için ise SpringFox çıkarılmıştır.
- Swagger’ın önemli bir amacı RestAPI için bir arayüz sağlamaktır.
- Swagger ile gelen bir başka kullanım kolaylığı ise artık biz projelerimiz de API bilgilerimize Postman veya SoapUI üzerinden bakma mecburiyetimiz ortadan kalkmıştır. Bu işlemleri swagger üzerinden de gerçekleştirebilmekteyiz.
Spring Boot ile Swagger Projesi Oluşturma
Spring Boot projesini nasıl swagger dokümantasyonu haline getirebiliriz. Basit bir proje ile anlamaya çalışalım.
İlk önce bir maven projesi oluşturalım. Sonrasında projenize istediğiniz bir ismi verebilirsiniz.
Projemizi maven olarak oluşturduğumuz için bazı bağımlılıklar(dependency) ekleyerek spring boot projesi haline getirmemiz gerekiyor.
Projemiz bir swagger projesi olduğu için dependency olarak projemize eklememiz gerekmektedir. Bunun için;
Eklemesini yaptıktan sonra pom.xml hazır hale gelmiş oldu.
Projemizin amacı swagger yapısını iyice kavrayabilmek olduğu için basit bir user controller ve model sınıfımız olan User sınıfı oluşturarak Apı yazma işlemlerimize başlayacağız.
İlk önce model sınıfımızı oluşturalım. Bu sınıfımızda standart User bilgilerini oluşturduğumuz bir sınıf olacaktır.
Bu sınıfımızda getter, setter ve constructor oluşturmamak için Lombok annotations kullanacağız.
Burada dikkat etmemiz gereken önemli kısım @ApiModel ve @ApiModelProperty alanlarıdır.
ApiModel ile oluşturduğumuz API modelleri hakkında bilgi veririz. Böylece geliştiriciler hangi modelin ne için yazıldığını dokümantasyon üzerinden direk anlayabilirler.
ApiModelProperty ise model sınıfında eklediğimiz değerlerimizin üzerinde açıklama yapmak için kullanırız.
Model sınıfımızı oluşturduktan sonra bu sınıf üzerinde işlem yapacağımız User Controller sınıfımızı oluşturalım. Bu sınıfımız ile kullanıcı ekleyebilir ve eklediğimiz kullanıcıları listeleyebileceğimiz metotlar oluşturacağız.
@Api ile sınıfımızın bir API dokümantasyonu olduğunu belirtiyoruz.
@ApiOperation ile metotlarımızın hangi işlemi yaptığını belirtiyoruz.
Gördüğünüz üzere eklediğimiz her annotation ile dokümanımızı zenginleştirebiliriz. Bu sayede API kullanacak geliştiricinin de işini kolaylaştırmış oluruz.
Bu işlemlerimizin ardından artık Swagger konfigürasyonlarını yazacağımız swagger config sınıfımızı oluşturalım. Daha sonrada @Configuration ve @EnableSwagger2 anatasyonlarını ekleyelim ve doküman türünü swagger olarak belirtelim.
Bu sınıfta yaptığımız işlemlere bakacak olursak, projemizin dokümante edilecek olan sınıflarını belirtmek için ilk önce hangi paket altında yer aldığını belirtiyoruz.
.paths ile belirttiğimiz kısım ise projemizin hangi Rest Controller için bu dokümantasyonu yazdığımızı belirtiyoruz. Ben bu kısımda genel bir kullanım yaptım ama siz isterseniz;
.paths(PathSelectors.regex(“/user.*”)) ile de belirtebilirsiniz.
ApiInfo metodumuz ile projemize ait doküman bilgilerimizi veriyoruz. Projemizin başlığını, açıklamalarını, versiyon bilgileri vs. belirttiğimiz bir alandır.
Gerekli ayarlarımızı yaptıktan sonra artık projemizi ayağa kaldırarak API dokümantasyonumuzu görebiliriz.
Projemizi ayağa kaldırdıktan sonra,
http://localhost:8080/user ‘ a giderek ilk önce projemizi başarılı bir şekilde ayağa kaldırıp kaldırmadığımıza bakıyoruz.
Eğer sizin de karşınıza bu çıktı geldiyse başarılı bir şekilde user bilgilerimiz oluşmuş demektir. O kadar yazdığımız doküman bilgilerimiz neden gözükmüyor diyorsanız eğer projemize dönerek konsolumuzda yazılan swagger adresini alarak API dokümantasyonunu görebiliriz.
Loglarımızı okuyarak aslında swagger için oluşan HTTP isteğimizi görebiliriz.
Ve artık yazdığımız API dokümantasyonu bu adresten inceleyebilirsiniz.
Sıra geldi swaggerın bize sunmuş olduğu güzelliklere :) Swagger editörü sayesinde postman üzerinden yaptığımız bütün işlemleri yapabiliriz.
Öncelikle https://editor.swagger.io/ adresine giderek yukarıda oluşturduğumuz bilgileri bu sayfaya kopyalayalım.
POST’a tıklayıp try to it! butonu ile istediğimiz değeri gönderebiliriz.
- Swagger’ın bize sunmuş olduğu bir başka güzellik ise direk projemizi swagger-ui ara yüzü ile kullanmamızı da sağlayabiliyor. Bunun için pom.xml e gelerek bir dependency daha eklememiz gerekiyor.
Swagger editörü ile yaptığımız tüm işlemleri bu ara yüz ile de aynı şekilde yapabiliriz.
Proje kodlarına aşağıdaki linkten ulaşabilirsiniz.
Bu haftaki konumuz Spring Boot projemizi Swagger Api haline dönüştürmekti. Siz de bundan sonra oluşturduğunuz backend projelerini swagger haline getirerek geliştiriciler için daha okunur bir API dokümantasyonu oluşturabilirsiniz.
Sağlıkla Kalın! :)
