SpringFox — > SpringDoc kütüphanesi geçişi nasıl yapılır ? (Swagger Version Upgrade)

Upgrade işlemine başlamadan önce Swagger ile ilgili soru işaretleriniz varsa aşağıdaki yazılarımı okumanızı öneririm;

[embed]Swagger UI Nedir ? Kullanıcıların API çağrılarını doğrudan tarayıcıda denemelerine olanak tanıyan etkileşimli API belgeleri oluşturmak…dileksen3417.medium.com

[embed]Swagger3 Anotasyonları Nelerdir? Nasıl Kullanılır? Bir önceki yazımda SpringBoot 3 ile birlikte Swagger kullanımı, kurulum ve config ayarlarının nasıl yapılacağını…dileksen3417.medium.com

Spring Boot 3 versiyonuna geçişin ardından SpringFox sürümünde bazı hatalarla karşılaştım. SpringFox’u son sürüme yükseltmeme ve communitynin önerdiği annotation vb ayarları uygulamama rağmen hala runtimeda hatalar almaya devam ediyordum. Biraz daha kapsamlı araştırma yaptığımda SpringFox’un versiyon updatelerinde Spring Boot’a ayak uyduramadığını, yerine SpringDoc’a geçmenin daha kesin bir çözüm olduğu kanaatine vardım. İşte bununla ilgili örnek bir tartışma :

[embed]Springfox 3.0.0 is not working with Spring Boot 2.6.0 Springfox 3.0.0 is not working with Spring Boot 2.6.0, after upgrading I am getting the following error…stackoverflow.com

Projemizi SpringDoc’a geçirelim!

• İlk önce pom dosyamızı düzenlemekle başlayalım; springfox kütüphanesini kaldıralım, yerine springdoc bağımlılığını ekleyelim.

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

yerine:

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

• Maven reload yapalım, build alalım. Aşağıdaki gibi hatalarla karşılaşmamız kaçınılmaz :)

• Swagger 2 anotasyonlarını Swagger 3 anotasyonlarıyla değiştirmeliyiz. Swagger 3 anotasyonları için paket yolu bu olacaktır : io.swagger.v3.oas.annotations.
• İşte bazı dönüşüm örnekleri ;

@Api→@Tag

@ApiIgnore→ @Parameter(hidden = true)veya @Operation(hidden = true)veya@Hidden

@ApiImplicitParam→@Parameter

@ApiImplicitParams→@Parameters

@ApiModel→@Schema

@ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)

@ApiModelProperty→@Schema

@ApiOperation(value = "foo", notes = "bar")→@Operation(summary = "foo", description = "bar")

@ApiParam→@Parameter

@ApiResponse(code = 404, message = "foo")→@ApiResponse(responseCode = "404", description = "foo")

yerine :

• SwaggerConfig Docket değişimi :

Eğer birden fazla bean tanımınız varsa, Dokcet’ı GroupedOpenApi bean ile değiştirin :

eski :

  @Bean
  public Docket publicApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
              .paths(PathSelectors.regex("/public.*"))
              .build()
              .groupName("springshop-public")
              .apiInfo(apiInfo());
  }

  @Bean
  public Docket adminApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
              .paths(PathSelectors.regex("/admin.*"))
              .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
              .build()
              .groupName("springshop-admin")
              .apiInfo(apiInfo());
  }

yeni :

  @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }

Yalnızca bir tane Docket varsa, onu kaldırın ve bunun yerine application.properties ‘eözellikleri ekleyin, değerleri kendi projenizin paket yoluna ve api’lerinizin base path’ine göre ayarlamalısınız.

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

ve OpenAPIbean türünü ekleyin :

  @Bean
  public OpenAPI springShopOpenAPI() {
      return new OpenAPI()
              .info(new Info().title("SpringShop API")
              .description("Spring shop sample application")
              .version("v0.0.1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
              .externalDocs(new ExternalDocumentation()
              .description("SpringShop Wiki Documentation")
              .url("https://springshop.wiki.github.org/docs"));
  }

→ İşte tam bir dönüşüm örneği :

Eski:

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket postsApi() {
    return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .useDefaultResponseMessages(false)
      .select()
      .paths(Predicates.not(PathSelectors.regex("/error.*")))
      .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
      .title("Swagger API Documentation")
      .version("v1.0")
      .build();
  }

}

Yeni:

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration
public class SwaggerConfig {

  @Bean
  public OpenAPI springShopOpenAPI() {
    return new OpenAPI()
      .components(new Components().addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic").in(SecurityScheme.In.HEADER)))
      .info(new Info().title("Swagger UI") //any title you want
        .description("Swagger API Documentation") //any description you want
        .version("v1.0"));
  }

}

• Spring Boot Security, Swagger’ın endpointlere ve dokumanlara erişimine izin vermiyor. Güvenlik yapılandırmasını gerçekleştirdiğimiz SecurityConfiguration classında bazı düzenlemeler yapmamız gerekiyor.

filterChain methodunda Swagger UI için gerekli olan URL’leri ve ihtiyaç duyduğu kaynakları görüntülemek için yetkilendirmemiz gerekiyor.

requestMatchers methodunda verilen api base path’i kendi projenize göre set etmelisiniz

Bu düzenlemelerden sonra applicationı ayağa kaldırıp http://localhost:8085/swagger-ui/index.html#/ (8085 yerine uygulamanızın ayağa kalktığı portu girin) urle girdiğinizde swagger ui ekranında api dokumanlarını görmeniz gerekir.

İşte bu adımda alabileceğiniz birkaç hata ve çözümü :

1. java.lang.ClassNotFoundException: jakarta.xml.bind.annotation.XmlElement

Çözüm : add jakarta EE 10 to pom

[embed]Java 11 package javax.xml.bind does not exist I'm trying to deserialize XML data into a Java content tree using JAXB, validating the XML data as it is unmarshalled…stackoverflow.com

2. No operations defined in spec!

Çözüm: SecurityConfiguration filterChain methodunda taranacak url yolunu doğru yazdığınızdan emin olun!

application.properties classında taranacak paketleri doğru belirttiğinizden emin olun. Eğer bu ayara ihtiyacınız yoksa app proptan kaldırın.

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