Spring Boot ve Security ile Swagger Kullanımı

Swagger nedir?

Swagger, REST API tasarlamak, oluşturmak ve geliştirmek için kullanılan bir sözleşme standardıdır. Bunun için yardımcı araçlar sunmaktadır. REST API'yi web tarayıcıları aracılığıyla kullanıcı dostu bir arayüzle göstermek için kullanılır.

Swagger nasıl kullanılır?

Peki Swagger kullanımı nasıldır? Spring Boot projelerinde Springfox'un Swagger uygulamasını kullanmak için, aşağıdaki bağımlılıklar “pom.xml”e eklenmelidir.

"springfox-boot-starter" bağımlılığı, API dokümanlarını oluşturmak için kullanılır. "swagger-ui", bu belgeleri güzel bir şekilde görüntülemek için kullanılır ve ayrıca kullanıcılar ile “API endpointler” arasında tarayıcı üzerinde etkileşim sağlar.

pom.xml'e bağımlılıklar eklendikten sonra, aşağıda görüldüğü gibi projeye bir “Configuration” class eklenmelidir. Yapılandırmadan sorumlu olan “Docket Bean”, bu sınıfta tanımlanmalıdır.

Proje içinde taranmasını istediğiniz klasörler/paketler, "RequestHandlerSelectors" ile tanımlanabilir. Swagger'da sadece “Controller Class”larını ekleyebilirsiniz veya bununla beraber “Entity”lerinizi ekleyebilirsiniz.

“ApiInfo”nun eklenmesi isteğe bağlıdır ve REST API belgeleri hakkında başlık, açıklama ve iletişim bilgileri gibi ek bilgiler sağlar.

Yapılması gereken bağımlılıklar (dependency) ve Docket Bean tanımlamaları REST API dokümanlarını gösterecek “swagger-ui” için yeterli olur. API dokümanını daha okunabilir ve bilgilendirici hale getirmek için, “Controller Class”larına ve “Endpoint”lere "@Api" ve "@ApiOperation" anotasyonları eklenebilir.

Swagger-ui, linkte yayınlanmaya hazır durumdadır.

Aşağıdaki görselde Swagger tarafından desteklenen REST API dokümanının ana sayfasını görebilirsiniz. Görüldüğü gibi, “Project Controller”da bulunan “endpoint”ler listelenmiştir. Ayrıca, “Entity”ler de sayfanın altında bulunabilir.

Swagger-ui sayfasında, API endpoint’lere istek gönderilebilir ve dönen yanıtlar kontrol edilebilir. "Try It Out" örneği, güvenlik kullanımını da içeren sonraki bölümde gösterilecektir.

Endpoint’lerin yanı sıra, “Entity” ve “alanlar”ı da görülebilir. Aşağıda görüldüğü gibi, alanlara ait “validation”lar da modele eklenmiştir. @NotNull ve @Size anotasyonları ile "projectName" alanı zorunlu olarak işaretlenmiş ve "projectCode" uzunluğunun da 0 ile 5 arasında olması gerektiği belirtilmiştir.

Spring Security ile Kullanımı

REST API’de “authentication” kullanılmadığı durumda ancak Swagger-ui, yukarıdaki yapılandırma ile kullanılabilir. Bilindiği üzere, web servislerini yetkilendirme ve kontrol adımları olmadan kullanmak nadir görülebilir. Bu nedenle, bu bölümde Swagger'ı “Spring Securtiy” ile nasıl yapılandıracağımızı göreceğiz.

Tarayıcıdan swagger-ui adresine erişmek için, ilk olarak izin listesi düzenlenmelidir. Aşağıda gösterildiği gibi Swagger ile ilgili adresler, "WebSecurityConfigurerAdapter"ı implement eden yapılandırma sınıfınıza eklenmeli ve “permitAll” ile izin verilmelidir.

Swagger ile ilgili adresleri izin listesine eklemek, "swagger-ui" sayfasına erişmek için yeterlidir. “Controller Class”ları, “Endpoint”ler ve “Entity”ler, yukarıda gösterildiği gibi tarayıcıda görülebilir.

REST API'nin endpoint’lerine erişmek ve çağırmak için ise, SecurityContext ve SecurityScheme de “Docket Bean”e eklenmelidir.

SecurityScheme ve SecurityContext örnek tanımlamaları aşağıda görülebilir. SecurityScheme için aşağıdaki örnekte “JWT” kullanımı gösterilmiştir.

Bu örnekle beraber, güvenli REST API'lerde de swagger üzerinden endpoint’lere istek gönderebilirsiniz. Böylece Swagger-ui sayfasında, istekleri gönderebilmek için yetkilendirmeyi sağlayacak yeni bir "Authorize" butonu eklenmiş oldu.

"Authorize" butonuna tıkladığınızda bir pencere açılır ve buraya kimlik doğrulaması için “token”ı yazabilirsiniz. Başarılı bir kimlik doğrulamasından sonra, endpoint’ler çağrılabilir.

Yetkilendirme isteyen bir endpoint bu şekilde çağrılabilir. API endpoint’e "execute" butonu ile istek gönderilirken, “header”a token eklenir. API endpoint’ten dönen JSON cevabı ise, “Response Body” içinde görülebilir.