Spring Boot 3 + Swagger 3 적용

버전마다 워낙 XX 맞아서 최신 버전 적용하는 것만 기록 ...

---

Dependency

우선 적용하려는 버전은 Spring Boot 가 3.0.5 이지만 3.x.x 면 다 될것 같다.
기존에 사용중이던 의존성이 뭐가 됐든 swagger 관련된 의존성을 삭제한다.
그리고 다음 한 줄을 추가

    // swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

글 작성 기준(240303) 가장 최신 버전으로 적용했다. (따끈따끈한게 좋으니까)

---

SwaggerConfig

딱히 뭐 설정안하고 바로 쓰고 싶으면 Config 파일을 별도로 생성안해도 괜찮다. 기본적인 것은 알아서 해준다.
하지만 Info 들의 정보라던가 Security 부분을 따로 설정하고 싶어서 파일을 추가 했다.
참고로 거의 대부분의 속성 정의는 application.yml 에서 가능하다. 관련된 속성은 여기를 참고

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.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Collections;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI(){
        SecurityScheme securityScheme = new SecurityScheme()
            .type(SecurityScheme.Type.HTTP)
            .scheme("Bearer")
            .bearerFormat("JWT")
            .in(SecurityScheme.In.HEADER)
            .name("Authorization");

        SecurityRequirement securityRequirement = new SecurityRequirement().addList("JWT");

        return new OpenAPI()
            .components(new Components().addSecuritySchemes("JWT", securityScheme))
            .security(Collections.singletonList(securityRequirement))
            .info(
                new Info()
                    .title("title 쓰고싶은 것 쓰기")
                    .description("{프로젝트명 정도 쓰면 될듯} API")
                    .version("v1.0.0 버전은 알아서 쓰기 v 안붙여도 됨")
            );
    }

}

적용된 프로젝트 내부에서는 JWT 토큰을 사용하기 때문에 설정을 추가하였다.

---

/swagger-ui/index.html vs 나

swagger 3 버전부터 url 이 바뀌었다고 한다. 기존의 swagger-ui.html 에서 swagger-ui/index.html 로 바뀌었는데 이전 url 로 접근하면 자동으로 리다이렉트 되긴한다. 하지만 정작 만난건 404 page ... 그래서 당연하게 addResourceHandler 에 /swagger-ui/** 를 추가했다.

그래도 404 가 나와서 왜 그런지 구글링을 막 해봤더니 추가한 의존성으로 인해 webjars 라는 것이 같이 추가가 되는데 이를 addResourceLocations 에 추가를 해줘야 한다. 2.3.0 기준이라면 5.10.3 이 추가가 될 것이다.

그래서 다음을 또 추가한다. classpath:/META-INF/resources/webjars/swagger-ui/5.10.3/ 맨 끝에 / 꼭 붙여야한다.

애플리케이션을 실행하고 swagger 주소로 접속하면 정상적으로 나올 것이다. 망할 pet store 로 !!!

그래서 default url 에 대한 접근을 disable 처리하는 속성이 있어서 다음을 application.yml 에 추가했다.

springdoc:
  swagger-ui:
    disable-swagger-default-url: true

그리고 재시작 . . . 그리고 들려온
pet store: Hello
여튼 당장 저 한 줄이 안먹힌다. 이 내용도 조금 찾아봤는데 이전 버전과의 yml 이 통합이 안되어서 ? 생기는 문제 같다고 하더라.
그래서 나중에 찾아보려고 한다.

현재까지의 상태에서 default 가 pet store 로 나온다면 상단의 explore 쪽에 본인의 api-docs url 을 검색하면 api 들이 보일 것이다. 예를 들어 application.yml 에서 springdoc.api-docs.path 를 따로 지정하지 않은 경우 기본값인 /v3/api-docs 일 것이니 http://localhost:{port}/v3/api-docs 일 것이다.

---

@EnableWebMvc

이 글을 작성한 애플리케이션의 경우 @EnableWebMvc 을 사용하지 않고 WebMvcConfigurationSupport 으로 따로 상속받아서 정의하다 보니 addResourceHandlers 를 따로 써줘야했다. 물론 이걸 쓰지않는 경우라면 @EnableWebMvc 를 통해서 곧바로 swagger 에 접근이 가능하다. 하지만 다른 내부 소스들이 충돌나고 그래서 일단 addResourceHandlers 추가하는 방식으로 구현했다.