Springboot3.x 버전에서의 Springdoc 라이브러리를 통한 Swagger 적용

Springdoc는 무엇인가?

Springdoc는 Springboot 프로젝트를 사용하여 API 문서를 자동으로 생성하는 Java 라이브러리 입니다. 이 라이브러리는 실행 시간에 어플리케이션을 검사하여 Spring 구성, 클래스 구조 및 다양한 주석을 기반으로 API를 만듭니다. 

 

Swagger UI를 제공하는 라이브러리는 Springfox 뿐만 아니라, Springdoc 에서도 해당 라이브러리를 제공합니다.

최근에는 Springdoc 을 사용하는 것을 더 선호하는 편이라고 합니다.

 

Gradle dependency

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2")

 

Springdoc에서의 Swagger UI 설정은 Springfox 설정과 차이가 있습니다. Springfox의 경우 대부분 java 클래스에서 설정하지만, Springdoc는 config 클래스에서 기본 문서 페이지만 설정하고 나머지 설정은 모두 applicaton.yml or application.properties에서 설정하게 됩니다. 

 

SwaggerConfig.class

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("User-Sample API")
                .description("Springdoc Swagger 테스트")
                .version("1.0.0");
    }
}

 

application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html

--- or

springdoc:
  packages-to-scan: com.example.controller
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: alpha

 

 

위와 같이 기본 설정만으로도 swagger을 작동할 수 있습니다. (http://localhost:8080/swagger-ui)

 

Swagger-UI

 

 

더 많은 설정을 위해서는 아래와 같이 Controller에 코드를 추가합니다.

 

@Tag(name = "유저(users)", description = "유저 API")
@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/users")
public class UserController {

    private final UserService userService;

    @Operation(summary = "email 을 통한 유저 조회", description = "email 을 통해 유저를 조회합니다.")
    @Parameter(name = "email", description = "유저 이메일", required = true)
    @GetMapping("/{email}")
    public ResponseEntity<ApiResponse> getUser(@PathVariable String email) {
        UserResponse userResponse = UserResponse.from(userService.getUser(email));
        return ResponseEntity.ok(ApiResponse.of(HttpStatus.OK, HttpStatus.OK.series().name(), userResponse));
    }
}

 

tag를 통한 화면 구성