[Spring Boot] Spring Boot 3 이후 Swagger 적용 - springdoc (not springfox)

Swagger

: 애플리케이션의 REST API (Open API) 문서를 자동으로 구성해주는 도구

Spring Boot 3 이후 버전은 Swagger 적용을 위해 springdoc-openapi(github)를 사용하는 것이 권장됨
springfox에 비해 활발한 업데이트가 이루어지고 있으며, 공식문서가 읽기 편하고 API 그룹핑 설정이 간단함

(기존의 springfox-swagger 의존성을 추가하는 과정에서 해결되지 않는 오류에 빠지게 되어 알아보게 됨)

아래는 공식 홈페이지에 적혀있는 문구임

따라서 springdoc-openapi v2를 사용할 것임

공식 홈페이지

최신 버전인 v2.3.0을 적용시켜보자

의존성

Maven

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.3.0</version>
   </dependency>

Gradle

dependencies {
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
}

Swagger 적용 확인

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

Swagger-ui Configuration

springdoc-openapi는 swagger-ui official properties를 지원함

Official Swagger-ui Configuration 참고

아래는 예시 코드(config/SwaggerConfig.java)임

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
        info = @Info(title = "Restaurant Recommendation API",
                description = "식당 추천 서비스 Restaurant Recommendation API 문서",
                version = "v1"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi chatOpenApi() {
        String[] paths = {"/**"};

        return GroupedOpenApi.builder()
                .group("Restaurant Recommendation API")
                .pathsToMatch(paths)
                .build();
    }
}

application.yml (필요에 따라 적용)

springdoc:
  packages-to-scan: kr.ac.sejong.ds.restaurant  # Swagger 문서를 생성할 컨트롤러가 포함된 패키지를 지정
  paths-to-match: /**  # 문서화할 경로를 지정합니다. /**는 모든 경로를 의미
  
  swagger-ui:
    path: api-docs  # 생성된 API 문서의 경로를 지정
  api-docs:
    path: /api-docs/json  # 생성된 API 문서의 경로를 지정
    groups:
      enabled: true  # 그룹별로 API 문서를 생성할지 여부 (기본값: true)
  cache:
    disabled: true  # Swagger 문서의 캐싱을 사용하지 않도록 설정 (기본값: false)
    
  # 기본적으로 사용할 요청 및 응답의 미디어 타입을 설정
  default-produces-media-type: application/json;charset=UTF-8
  default-consumes-media-type: application/json;charset=UTF-8

Controller에 적용하기

// DeleteMemberController.java
@RestController
@RequiredArgsConstructor
public class DeleteMemberController {
 
    @Operation(summary = "회원 탈퇴 요청", description = "회원 정보가 삭제됩니다.", tags = { "Member Controller" })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK",
                    content = @Content(schema = @Schema(implementation = DeleteMemberResponse.class))),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
    })
    @DeleteMapping("/v1/member/{id}")
    ResponseEntity<DeleteMemberResponse> deleteMember(
            @Parameter(description = "회원 ID", required = true, example = "1") @PathVariable("id") Long id) {
        // 생략..
    }
}

• @Tag로 설정된 name이 같은 것 끼리 하나의 api 그룹으로 묶고, 그룹에 대한 설명을 기술할 수 있음
• @Operation으로 메서드에 대한 설명을 기술할 수 있음
• @ApiResponse로 응답 결과에 따른 response 구조를 미리 확인 가능