Swagger UI Nedir ? SpringDoc & SpringBOOT 3 Entegrasyonu

Kullanıcıların API çağrılarını doğrudan tarayıcıda denemelerine olanak tanıyan etkileşimli API belgeleri oluşturmak için kullanılan araçtır.

* OpenAPI Nedir?

OpenAPI Spesifikasyonu(eski adıyla Swagger Spesifikasyonu) REST API’lerimizi açıklamamıza yarayan bir yaklaşımdır. Bir OpenAPI dosyası, aşağıdaki gibi API’lerimizi tanımlamamıza olanak tanır:

• Kullanılabilecek endpointler ve operasyon bilgileri, or : /users ,GET /users, POST /users
• API’lerin input ve output bilgileri
• Kimlik doğrulama yöntemleri
• Lisans bilgisi, kullanım koşullar vb extra bilgiler

API spesifikasyonları YAML veya JSON olarak yazılabilir.

* Neden kullanmalıyız?

Developer bir application için API üretiyor. Aynı zamanda bir consumer(tüketici) var. Developer, yarattığı API’a consumerın erişmesini istiyor. Bu durumda consumer developerdan API bilgilerini talep edecektir;

• Hangi endpointleri çağırmalıyım?
• Bu api’lerin input ve outputları nelerdir?
• Sağlayacağı yanıt kodları nelerdir?
• Ne kadar yük getirir, hata kodları nelerdir…..

Gördüğünüz gibi ortada yanıtlanması gereken bir çok soru var. Bunun birden fazla API için istendiğini düşünelim.. Başka bir fazda bu apilerde değişiklik yapıldığını veya sisteme yeni müşterilerin dahil olduğunu ve her dahil olan müşterinin bu bilgileri tekrar talep ettiğini düşünün. Uygulama yaşam döngüsü devam ettiği sürece developer sürekli bu sorulara maruz kalacak, dokumanı sürekli yenilemek zorunda kalacaktır. Eminim hiçkimse bu işlere uzun süre vakit harcamak istemez :)

Bu işin en hızlı çözümü bir API dokumanı hazırlamak, tüm sözleşme bilgilerini burada tutmaktır. Bunu da Swagger ile sağlarız.

* Swagger’ı Projemize Nasıl Entegre Ederiz ?

Uygulamamızdaki Controller sınıflarında tanımladığımız API’lerimize ‘Swagger Metadata’ ekleriz. Api’lerin ne olduğunu, parametlerin ne için kullanılması gerektiğini belirtiriz. Hali hazırda swagger doğrudan koddan ve method imzalarından birçok bilgi elde eder. Fakat kendimiz daha fazla metadata ekleyerek consumer’ların bilmesi gerektiğini düşündüğümüz notları vs apiye ekleyebiliriz. Tüm bu ayarlamaların sonucunda Swagger bize HTML formatında okunabilir bir API Documentation üretir.

API’de güncelleme yapıldığında developer sadece gerekli metadataları günceller ve süper aracımız swagger da api dokumanını günceller.

-- Uygulama :

Spring Io Initializr ‘dan SpringBoot 3.1.1 , Maven, Java 17 versiyonlarını seçiyoruz. SpringBoot 3 ile birlikte SpringFox (springfox-swagger2 :: 3.0.0(şu an için en yeni versiyon)) kütüphanesi birlikte iyi çalışmıyor. Runtime’da bazı hatalara neden oluyor. Dokumanları incelediğimde SpringBoot 3 ile birlikte SpringDoc kullanılması öneriliyor.

Detaylar için inceleyebilirsiniz :

https://stackoverflow.com/questions/70178343/springfox-3-0-0-is-not-working-with-spring-boot-2-6-0

[embed]How to run Swagger 3 on Spring Boot 3 Using a fresh Spring Initialzr with Java17 and Spring Boot 3.0.0, and an extra addition to the pom.xml for Springfox…stackoverflow.com

https://stackoverflow.com/questions/69799828/java-springdoc-apiresponses-how-to-define-a-list-as-return-object-using

[embed]Migrating from SpringFox org.springdoc springdoc-openapi-starter-webmvc-ui 2.1.0 Replace swagger 2 annotations with swagger 3 annotations (it is…springdoc.org

• İlk adım, Swagger’ı uygulama pom’una ekleyelim. Bunun için SpringDoc kütüphanesini kullanacağız. Aynı zamanda spring-boot-starter-validation bağımlılığını da eklemeliyiz, eklemediğimiz takdirde compiler anında bir exception alırız bunun da nedeni https://springdoc.org/ sitesinde de belirtildiği gibi Jakarta JSR -303 bağımlılığına ihtiyaç duymasıdır.

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.1.0</version>
</dependency>

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

• username, firstname, lastname.. gibi alanları içeren bir User entity tanımlayalım. Bu entity’e bağlı olarak UserService, UserServiceImpl ve UserRepository classlarını da create edelim.

API’ları tanımladığım controller classı şu şekilde;

@RestController
@RequestMapping(value = "/users")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping
    @ResponseBody
    public List<User> getAll() {
        return userService.getAllUsers();
    }

    @PostMapping
    public User saveUser(@Valid @RequestBody UserDTO userDTO)
    {
        return userService.addUser(userDTO);
    }

    @PutMapping("/{id}")
    public User updateUser(@RequestBody UserDTO userDTO, @PathVariable("id") Long userId)
    {
        return userService.updateUser(userDTO, userId);
    }

    @DeleteMapping("/{id}")
    public String deleteUserById(@PathVariable("id") Long userId)
    {
        userService.deleteUser(userId);
        return "Deleted Successfully";
    }

}

Kodların tamamına erişmek için GitHub hesabıma bakabilirsiniz.

[embed]GitHub - dileksen3417/MediumTutorialProject Contribute to dileksen3417/MediumTutorialProject development by creating an account on GitHub.github.com

• Uygulamayı ayağa kaldıralım ve http://localhost:8085/swagger-ui/index.html#/ adresine gidelim. 8085 portuna uygulamanız hangi porttan ayaklanıyorsa o portu yazmanız gerekmektedir. Bizi aşağıdaki gibi bir ekran karşılayacak:

/v3/api-docs ‘a tıkladığımızda JSON dokumanı elde ederiz. İşte bu dokumanın bir kısmı;

Görüldüğü gibi izin verdiğimiz tüm componentları tarar ve API’lerin dokumanlarını oluşturur. Aynı zamanda applicationda tanımladığımız POJO classların da dokumanını oluşturur.

OpenAPI definition adında bir başlık görüyoruz, bunu projemize uygun şekilde kendimiz tanımlayalım. SwaggerConfig adında bir class oluşturalım.

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Upcycling")
                        .description("Created by DSEN to Medium Tutorials")
                        .version("v1.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("Medium Documentation")
                        .url("https://medium.com/@dileksen3417/swagger-ui-nedir-2e2a4e5dc882"));
    }

}

Başlık ve açıklama kısmının aşağıdaki şekilde değiştiğini görebiliriz.

Hangi yolların filtreleneceğini veya hangi paketlerin taranacağını açıkça belirtmek için application.properties dosyasına aşağıdaki tanımları ekleyebilirsiniz.

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

• UI üzerinden birkaç deneme yapalım;

user-controller altındaki GET /users endpointine tıklayalım, ardından ‘Try it out’ butonuna tıklayalım. Execute butonuna tıkladığımızda Response Code ve Response Body döndüğünü görebiliriz.

• Şu an UI üzerinde herhangi bir authorization tanımı yok. Uygulamanızda bir user-pass ile token alarak servislere ulaşabilme kontrolü olduğunu varsayalım. SwaggerUI’da test etmek istediğimiz her serviste tek tek token değerini girmemiz gerekecek. Fakat bunun da kolay bir yolu var, SwaggerConfig classına SecurityScheme tanımı yaparak authorization sağlayabiliriz.

@Configuration
@SecurityScheme(
        name = "Basic Auth",
        description = "Get a XAuth-Token for access to all APIs",
        scheme = "basic",
        type = SecuritySchemeType.HTTP,
        in = SecuritySchemeIn.HEADER
)
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Upcycling")
                        .description("Created by DSEN to Medium Tutorials")
                        .version("v1.0")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("Medium Documentation")
                        .url("https://medium.com/@dileksen3417/swagger-ui-nedir-2e2a4e5dc882"));
    }

}

— Auth type olarak JWT Bearer, Basic Auth vb kullanılabilir, uygulamadaki auth tercihinize göre bunu ayarlamanız gerekmektedir. Yukarıdaki Basic Auth için olan implementasyonu görüyorsunuz. JWT için aşağıdaki implementasyonu kullanabilirsiniz.

Tekrar SwaggerUI ekranına geldiğimizde Authorize adında bir buton eklendiğini görüyoruz. Tıkladığımızda user pass ile token üretebiliriz. Bu tokenı swagger kendi içerisinde saklıyor ve çağırdığınız apilere veriyor.

Controller classında hiçbir ek açıklamaya ihtiyaç olmadan nasıl API dokumanlarını oluşturabileceğimizi gördük. Bir sonraki konumuz Swagger 3 annotationların detaylı incelenmesi ve örnekleri olacak. Takipte kalın :)