Swagger nedir? Spring Boot ile Swagger Nasıl Kullanılır?
Swagger Nedir?
Web API geliştirirken en önemli konulardan birisi de dökümantasyon ve test gereksinimidir. Bu noktada Swagger yazılımcıların yardımına koşuyor.
Kısaca Swagger, JSON kullanılarak ifade edilen RESTful API’leri açıklamak için bir Arayüz Tanımlama Dilidir. Swagger, RESTful web hizmetlerini tasarlamak, oluşturmak, belgelemek ve kullanmak için bir dizi açık kaynaklı yazılım aracıyla birlikte kullanılır.
Peki, RESTful API nedir?
REST (Temsilî Durum Aktarımı; İngilizce: Representational state transfer) Web protokolleri ve teknolojilerini kullanan bir dağıtık sistemdir. Burada ki temsili sözcüğü verinin temsilini kastetmekte olup, onunla ilgili durumun aktarılması olarak düşünülebilir.
REST prensiplerini sağlayan sistemler de RESTful olarak adlandırılır.
RESTful sistemler çoğunlukla HTTP protokolü üzerinden Web tarayıcıları tarafından sayfaların transferinde de kullanılan HTTP fiilleri (GET, POST, PUT, DELETE vs.) ile haberleşirler.
Aktarılan verinin formatı HTML, JSON, XML ya da farklı bir tipte olabilir. REST, bu konuda bir kısıtlama getirmez.
Günümüzde yaygın olarak RESTful sistemler ile birlikte JSON formatı kullanılmaktadır.
Swagger’a geri dönecek olursak;
Swagger araçları şunları içerir:
- Swagger Editor: OpenAPI özelliklerini yazabileceğiniz browser tabanlı editör sunar.
- Swagger UI: OpenAPI özelliklerini etkileşimli API belgesi olarak sunar.
- Swagger Codegen: Bir OpenAPI’dan sunucu taslakları ve istemci kütüphaneleri oluşturur.
Swagger bir çok dili desteklemektedir. Spring Boot ile kullanımı için SwaggerFox çıkarılmıştır. Bu yazıda örnek olarak Maven projesine eklenmesini ve kullanımını inceleyeceğiz.
Öncelikle kısaca Maven projesi ne demek buna bakalım:
Maven, öncelikle Java projeleri için kullanılan bir yapı otomasyon aracıdır. Maven ayrıca C #, Ruby, Scala ve diğer dillerde yazılmış projeleri oluşturmak ve yönetmek için de kullanılabilir.
Maven, projemizi geliştirirken ve proje bağımlılıklarının kontrolünü sağlarken kolaylık sağlamasının yanında aynı zamanda IDE bağımsız yazılım geliştirmeyi de amaçlar.
Maven projenizde bulunacak olan pom.xml dosyası projenizin adı, paketi, versiyon numarası, repolar, dependencyler ve daha birçok bilgiyi barındırabilir. Projenize ekleyeceğiniz dependencyleri (bağımlılıkları) buradan yönetiyor olacaksınız.
İstediğiniz bağımlılığı https://mvnrepository.com/ adresinden kolayca aratabilirsiniz.
Şimdi Maven Projemize Swagger’ı nasıl ekleyeceğimiz konusuna geçelim.
Swagger’ın Maven Projesine Eklenmesi
Swagger’ın Maven projesine eklemek için, projemiz ile birlikte gelen pom.xml dosyasında dependencies kısmına dependency olarak eklenmesi gerekir.
Kodları şuradan alabilirsiniz:
Swagger’ın Konfigüre Edilmesi
Application class’ına Docket bean implemente ederek konfigüre etme işlemine başlıyoruz:
Not: apis() ile dokümana dahil edilecek paketleri belirtiyoruz. Tüm paketleri dahil etmek isterseniz RequestHandlerSelector.any() kullanabilirsiniz. Belirlerdiğiniz bir base paketi kullanmak için RequestHandlerSelector.basePackage(“…”) kullanabilirsiniz.
Kodları şuradan bulabilirsiniz:
Uygulamayı Ayağa Kaldırmak
Uygulamamızı çalıştırdıktan kaldırdıktan sonra, http://localhost:8080/…/swagger-ui.html adresinden dökümantasyona ulaşabilir ve testlerimizi gerçekleştirebiliriz.
Swagger dökümantasyonumuz yukarıdaki gibi görünüyor olmalı.
Uygulama içerisinde geliştirdiğimiz Request-Response işlemlerinin bir listesini göreceğiz. Bu şekilde Postman ile gerçekleştirdiğimiz tüm işlemleri gerçekleştirebiliriz.
Kolay Gelsin..
Kaynaklar:
