API’ler tüketilmek üzere(consume) tasarlandığından, tüketicinin API’nizi hızlı bir şekilde uygulayabilmesini ve anlaşılabilirliğini sağlamak önemlidir. Bu sebepledir ki api dokümantasyonu olmazsa olmazdır. Dokümantasyon hazırlamak da çoğumuza bir işkence gibi geliyor. Ayrıca hadi diyelim zar zor bir doküman oluşturdunuz güncelliğini korumak ve okunabilirliğini sağlamak da bir o kadar zor olabiliyor.
Bir tüketici dokümana baktığında “Bu servis ne iş yapar, tanımı nedir, içerisinde hangi operasyonları barındırır, bu operasyonların kullanım şekli nasıl olmalıdır, giriş çıkış parametreleri ne türdedir? ” gibi soruların cevaplarını alabiliyor olması gerekir.
Swagger Nedir ?
Swagger, Rest API’leri tasarlamanıza, oluşturmanıza, belgelendirmenize ve kullanmanıza yardımcı olabilecek OpenAPI şartnamesi etrafında oluşturulmuş bir dizi açık kaynaklı araçtır. Büyük Swagger araçları şunları içerir:
Swagger Editor – OpenAPI özelliklerini yazabileceğiniz tarayıcı tabanlı editör.
Swagger UI – OpenAPI özelliklerini etkileşimli API belgesi olarak sunar.
Swagger Codegen – bir OpenAPI spesifikasyonundan sunucu taslakları ve istemci kütüphaneleri oluşturur.
Swagger UI Kurulumu
Basit bir SpringBoot örneği üzerinden anlatacağım. Öncelikle pom.xml içerisine swagger-ui bağımlılıklarını ekliyoruz.
Daha sonra Swagger konfigürasyonu için aşağıdaki swagger konfigürasyon sınıfını oluşturuyoruz.
Swagger ayarları artık hazır. Şimdi Personel işlemlerinin yapıldığı rest servislerimizi yazalım.
Uygulamamızı ayağa kaldırıyoruz ve http://localhost:8080/swagger-ui.html adresinden rest apilerimizin belgelendiğini görebiliyoruz.
Swagger sunduğu standart ve araçlarla API tasarım, geliştirme, dokümantasyon ve test aşamasında kolaylık sağlamaktadır. Siz de hemen kullanıp sonuçları görebilirsiniz. Yukarıda yapılan örneğimizi github adresinden çekebilirsiniz.
