[팀프로젝트] Spring 2.6 이상에서 OpenAPI 3.X 사용하기(SpringDoc)

 

 

 

📚 참고자료

• 블로그 [호형] - Springboot에서 API Docs (Springdoc) 사용하는 방법 (1) => 링크
• 블로그 [호형] - Springboot에서 API Docs (Springdoc) 사용하는 방법 (2) => 링크
• 블로그 [soyeon207.log] - Swagger 란 ? (이론 + Spring boot 적용) => 링크
• SpringDoc 공식 문서 => 링크

---

 

 

 

Spring2.6 버전 이상에서 springfox-boot-starter:3.0.0를 dependencies에 추가한 후,

애플리케이션을 Run 하면 아래와 같은에러가 떴습니다.

rg.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

 

검색해본 결과, Spring 2.6 버전과 springfox-boot-starter3.0.0 이 호환성 문제라는걸 알게되었습니다

 

 

 

여기서 해결책은

1. Spring Boot 를 2.5x 버전대로 내리기
2.  application.yml 혹은 application.properties에 설정 추가
3. SpringDoc 을 사용하기(아래에 정리한 코드)

 

 

저는 2.5x 버전으로 내리거나 무언가(설정)을 추가하는 방식이 아닌 세번째 SpringDoc을 사용하는걸 선택했습니다.

 

 

---

1️⃣ build.gradle 의존성 추가

implementation "org.springdoc:springdoc-openapi-ui:1.5.9"

위 코드를 build.gradle안에 있는 dependencies에 추가해줍니다.

 

 

2️⃣ SwaggerConfig

@OpenAPIDefinition(
        info = @Info(title = "MatDi API",
                description = "MatDi API 명세서.",
                version = "v1"))
@Configuration
@RequiredArgsConstructor
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi customTestOpenAPi() {
        // /test 로 시작하는 API 들을 테스트 관련 API 로 그룹핑
        // member 로 시작하는 API 를 그룹핑 하고 싶다 라고 하면 메소드 이름을 변경하고 하나 더 만들어서 설정하면 됨

        String[] paths = {"/test/**"};

        return GroupedOpenApi
                .builder()
                .group("MatDi API")
                .pathsToMatch(paths)
                .addOpenApiCustomiser(buildSecurityOpenApi()).build();
    }

    public OpenApiCustomiser buildSecurityOpenApi() {
        // jwt token 을 한번 설정하면 header 에 값을 넣어주는 코드, 자세한건 아래에 추가적으로 설명할 예정

        return OpenApi -> OpenApi.addSecurityItem(new SecurityRequirement().addList("jwt token"))
                .getComponents().addSecuritySchemes("jwt token", new SecurityScheme()
                        .name("Authorization")
                        .type(SecurityScheme.Type.HTTP)
                        .in(SecurityScheme.In.HEADER)
                        .bearerFormat("JWT")
                        .scheme("bearer"));
    }

}

Swagger를 설정 및 jwt token을 추가하는 코드입니다.

 

 

 

3️⃣ application.properties

springdoc.default-consumes-media-type= application/json
springdoc.default-produces-media-type= application/json
springdoc.swagger-ui.path= /swagger-ui.html
springdoc.swagger-ui.disable-swagger-default-url= true
springdoc.swagger-ui.display-query-params-without-oauth2= true

application.properties에 위에 해당하는 설정을 추가해줍니다.

 

 

4️⃣ Swagger 접속 URL

 

3.x : http://localhost:8080/swagger-ui/index.html

 

로컬 환경에서 애플리케이션을 Run 한다음에 위 url로 접속하면 됩니다.