[Spring] Spring Boot 3.x에서 Swagger 설정하기

시작하기

Spring Boot 3.x로 프로젝트를 진행하며 Swagger의 필요성을 느꼈다. Swagger 설정이 간단했던 것으로 알고있어서 금방 끝날거라고 생각했지만 생각보다 고난을 겪었다. 관련 내용을 포스팅한 게시물도 적어보여 내가 정리해보려고 한다! 

 

Swagger 설정하기

dependency 설정

swagger를 사용하는 방법은 spring fox와 springdoc 두가지가 있다. 이전까지는 springfox를 사용하였었는데 Spring Boot 3.x에서 springfox를 사용하자 404 error가 발생했다. Spring Boot 3.x 버전에서는 무조건 springdoc을 사용해야 한다. 

 

적용할 프로젝트에 따라 dependency가 달라지게 되는데 Spring Boot 3.x의 경우 application.yml에 다음을 추가하면 된다. 이때 주의할 점은 Spring Boot 3.x에서 springdoc의 버전은 v2를 사용해야한다는 것!

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

 

Swagger 접속

사실 추가적인 설정없이 dependency만 추가하고 접속을 해도 swagger가 잘 작동되는 것을 확인할 수 있다. url은  http://{ip}:{port}/swagger-ui/index.html 로 접속하면 된다.

 

Swagger Document 설정

1. API Doc 설정하기

springdoc은 config에 많은 설정을 하지 않고 application.yml에서 간단하게 할 수 있다는 것이 장점이다.

Document 제목, 설명, 버전의 기본적인 설정은 다음과 같이 할 수 있다. 

@Configuration
public class SwaggerConfig {

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

    private Info apiInfo() {
        return new Info()
                .title("API Doc")
                .description("api 문서화")
                .version("1.0.0");
    }

}

 

 

2. appication.yml 설정하기

스캔할 package 경로, swagger path 등등을 설정할 수 있다. 더 많은 설정이 있으니 알아서 찾아보시길... 

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

 

Swagger Document 설명 추가하기

• @Tag : 컨트롤러에 대해 이름과 설명을 추가할 수 있다.
• @Operation : API에 대해 이름과 설명을 추가할 수 있다. 

@RestController
@RequiredArgsConstructor
@RequestMapping("/api")
@Tag(name = "컨트롤러", description = "컨트롤러 api")
public class RestController {

    private final ControllerService controllerService;

    @PostMapping("/controller")
    @Operation(summary = "저장", description = "저장합니다.")
    public ResponseEntity<Void> register(@RequestBody Request request){
        Long id = controllerService.save(request.toDto());

        URI uri = UriComponentsBuilder.fromPath("/controller/{id}")
                .buildAndExpand(id)
                .toUri();

        return ResponseEntity.created(uri).build();
    }