Spring Boot 3에 Swagger 적용하기(springdoc-openapi)

😨 실패1

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.1.3'
    id 'io.spring.dependency-management' version '1.1.3'
}

dependencies{

    ...
	implementation 'io.springfox:springfox-swagger2:3.0.0'
}

spring boot 3.1.3을 사용하고 springfox3.0.0을 추가했다. 결과적으로 SpringFox를 사용할 수 없는데, spring boot 3버전에서는 SpringFox 가 적용되지 않는다😭 현재 JakartaEE를 지원하는 SpringFox는 없기 때문이다.

그래서 이러한 예외를 만나게 되었다.
이를 해결하기 위해서는 spring boot의 버전을 낮추거나, springdoc-openapi를 이용해야 한다. 나의 경우는 springdic-openapi를 이용하기로 결정했다. 그 이유는 springfox는 3년 전 버전을 사용해야 하기 때문이다. 반면에 springdoc은 꾸준히 업데이트가 이루어지고 있다.

Swagger-UI를 제공하는 라이브러리의 업데이트 현황

[Spring Fox]
2020년 7월 3.0.0 버전을 마지막으로 업데이트 되고 있지 않음

[Spring Doc]
2023년 4월 1.7.0 버전 업데이트

😱 실패2

implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

최근까지 업데이트 되고 있는 SpringDoc으로 라이브러리를 교체했다.

그런데 404가 떴다.

버전이 맞지 않아서 발생한 문제였다. 홈페이지를 찾아보니 spring boot 3버전은 springdoc-openapi 2버전을 사용해야 한다고 한다🥲

🤓 성공

// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

springdoc-openapi 2버전으로 라이브러리를 다시 변경했다.

드디어! ui를 볼 수 있다.

demo
springdoc 의 demo는 아래 주소에서 확인할 수 있다.
https://demos.springdoc.org/demo-spring-boot-3-webmvc/swagger-ui/index.html

OpenAPI Bean 등록

OpenApi를 Bean으로 등록하여 API 문서의 제목과 설명, 버전을 추가했다.

@Configuration
public class SwaggerConfig {

  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
    .info(new Info()
    .title("커머스 프로젝트 API")
    .description("상품을 등록하고, 상품을 장바구니에 담는 기능을 제공합니다.")
    .version("1.0.0"));
  }
}

Spring Security 적용

Spring Security를 이용해서 인증/인가를 구현했다. /login 엔드포인트를 문서에서 확인하기 위해서는 추가 설정이 필요하다. application.yml 파일에 다음 설정을 추가했다.

springdoc:
  show-login-endpoint: true

설정을 추가하면 swagger-ui에 login endpoint가 추가된 것을 확인할 수 있다.

@Configuration
public class SwaggerConfig {

  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("커머스 프로젝트 API")
            .description("상품을 등록하고, 상품을 장바구니에 담는 기능을 제공합니다.")
            .version("1.0.0"))
        .components(new Components()
            .addSecuritySchemes("bearer-key",
                new io.swagger.v3.oas.models.security.SecurityScheme()
                .type(Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")));

  }

}

내가 작업한 프로젝트의 경우, 상품을 등록하는 경우에는 ADMIN 권한이 필요하다. token을 통해서 이를 구분하기 때문에 token을 담아서 요청할 수 있도록 설정을 추가해야 한다. config에 SecurityScheme을 추가해주면 문서에 Authorize 버튼이 추가된다. 좌물쇠가 열려있는건 현재 로그인 되지 않은 상태임을 나타낸다. 로그인에 성공하면 좌물쇠가 잠긴 모양으로 변경된다.

로그인 후 발급받은 토큰을 올바르게 입력하면 Authorization에 성공하고, 자물쇠가 잠기게 된다. /login 요청 후 받은 token을 value에 넣어주었다. 입력 시, Bearer 키워드는 제외하고 입력한다.

테스트로 요청을 해봤다. header Authorization 에 token이 담겨서 요청을 한 것을 확인할 수 있다.

Springfox Type javax.servlet.http.HttpServletRequest not present
springdoc-openapi