Springdoc을 이용한 Swagger 사용법(feat. SpringBoot 3.x.x)

개발자·2024년 1월 25일

Swagger 사용법에 관한 글을 무려 2022년에 작성하고 2023년까지도 프로젝트를 진행할 때 마다 잘 사용해왔다.
하지만 최근에 SpringBoot 3.2.1 프로젝트를 생성하고 적용하려하니 잘 되지 않았다.
찾아보니 SpringBoot 3.x.x부터는 springdoc이라는 다른 라이브러리를 사용해야 한다고 한다. 또한, 기존 방식에 사용했던 Springfox는 업데이트 되지 않고 있기에 SpringBoot 2.x.x를 사용중이더라도 Springdoc을 사용하는 것이 좋다고 한다.
새로운 Swagger 사용법을 정리해보자!

설정

1. build.gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

Springfox와 달리 Springdoc 사용시 Config 파일을 생성하지 않아도 Swagger API 문서가 생성된다.

접속 URL : http://localhost:8080/swagger-ui/index.html

기존의 java 파일을 통한 설정이 아닌 아래와 같이 application.yml을 통한 설정도 가능하다.

springdoc:
	default-consumes-media-type: application/json
	default-produces-media-type: application/json
    swagger-ui:
    	path: /swagger-ui.html

=> 자세한 설정은 여기를 참고

하지만, 나는 Authorization 관련 설정을 해줘야했기 때문에 Config파일을 생성했다.

2. SwaagerConfig

@Configuration
public class SwaggerConfig {

    private final String AUTH_TOKEN_HEADER = "Authorization";

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

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(apiInfo())
                .addSecurityItem(new SecurityRequirement().addList(AUTH_TOKEN_HEADER))
                .components(new Components()
                        .addSecuritySchemes(AUTH_TOKEN_HEADER, new SecurityScheme()
                                .name(AUTH_TOKEN_HEADER)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("Bearer"))
                );
    }

}

이렇게 Config 파일 작성시 좀 더 상세한 설정이 가능하다.
API를 package나 path에 따라 그룹화하는 기능도 추가 가능하다고 한다.

3. API

아래 코드와 같이 Controller에서 @Operation 어노테이션을 이용해 API 정보를 작성하면 된다.

@RestController
public class TestController {
  @GetMapping(value = "/call")
  @Operation(summary="테스트", description="테스트 중입니다.")
  public ResponseEntity<TestDTO> Call()  throws Exception {
    return ResponseEntity.ok(testService.test());
  }
}