Springboot 3.x에 swagger 적용 ( With. SpringDocs )

개요

Spring Boot 2.x에서 사용하던 Springfox 라이브러리가 더 이상 유지 관리되지 않아, Spring Boot 3.x에서 Swagger를 적용하려면 SpringDocs 라이브러리를 사용해야 합니다. 이 가이드는 SpringDocs를 사용하여 Swagger를 설정한다.

환경 설정

• SpringBoot: 3.3.1
• JDK: 17
• Build Tools: Gradle
• Editor: IntelliJ

Gradle 의존성 추가

build.gradle 파일에 다음과 같은 의존성을 추가합니다:

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

2. Swagger 설정 파일 작성

Swagger 사용을 위한 설정 파일을 작성합니다. 아래는 기본적인 설정 파일 예시입니다:

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

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

    private Info apiInfo() {
        return new Info()
                .title("CodeArena Swagger")
                .description("CodeArena 유저 및 인증, ps, 알림에 관한 REST API")
                .version("1.0.0");
    }
}

이 설정은 Swagger UI에서 보여줄 API 정보를 설정합니다.

3. Swagger UI 접속

Swagger UI에 접속하려면 다음 URL을 사용합니다:

<http://서버주소>:포트번호/swagger-ui/index.html#/

추가 설정

• Context Path가 설정된 경우: server.servlet.context-path=/api가 설정되어 있으면 해당 경로를 URL에 추가해야 합니다.
• URL 변경: Swagger UI의 기본 URL을 변경하려면 application.properties 또는 application.yml에 다음 속성을 추가합니다:
• springdoc.swagger-ui.path=/swagger-ui.html

4. 주요 어노테이션

@Tag

• API 엔드포인트의 그룹을 나타내기 위해 사용됩니다.
• Controller에 적용하여 해당 그룹의 정보를 표시할 수 있습니다.

@Tag(name = "알림 API", description = "컨트롤러에 대한 설명입니다.")
@RequestMapping("/alarm")
public class AlarmController { ... }

@Operation

• 각 API Endpoint에 대한 요약 및 설명을 지정하는 데 사용됩니다.

@Operation(summary = "수신함 리스트", description = "유저가 수신한 알림 목록을 최신순으로 정렬하여 전달")
@GetMapping("/receive")
public ResponseEntity<AlarmResultDto> receive(@RequestParam String userId) { ... }

@Parameter

• Endpoint의 파라미터 타입과 설명을 지정합니다.

@Parameter(name = "userId", description = "유저의 ID")
@GetMapping("/receive")
public ResponseEntity<AlarmResultDto> receive(@RequestParam String userId) { ... }

@ApiResponse

• API의 응답 구조를 설명합니다.

@Operation(summary = "알림 송신")
@ApiResponse(responseCode = "200", description = "송신 성공", content = @Content(schema = @Schema(implementation = AlarmReceiveDto.class)))
@PostMapping("/send")
public ResponseEntity<?> send(@RequestBody AlarmSendDto alarmSendDto) { ... }

5. 최적화: 인터페이스 사용

Swagger 설정을 Controller 코드와 분리하기 위해 인터페이스를 사용할 수 있습니다. 인터페이스에 Swagger 관련 어노테이션을 정의하고, Controller가 해당 인터페이스를 구현하도록 구성할 수 있습니다.

인터페이스 예시

@Tag(name = "알림 API", description = "알림에 관한 Controller")
public interface AlarmControllerDocs {

    @Operation(summary = "알림 송신", description = "알림을 송신합니다.")
    @Parameters(value = {
        @Parameter(name = "alarmType", description = "알림 타입"),
        @Parameter(name = "toId", description = "수신자 ID")
    })
    @ApiResponse(responseCode = "201", description = "알림 송신 완료")
    ResponseEntity<?> send(AlarmSendDto alarmSendDto);
}

Controller 예시

@RestController
@RequiredArgsConstructor
@RequestMapping("/alarm")
public class AlarmController implements AlarmControllerDocs {

    @PostMapping("/send")
    public ResponseEntity<?> send(@RequestBody AlarmSendDto alarmSendDto) {
        // 비즈니스 로직 처리
    }
}

이 방법을 사용하면 Swagger 문서를 유지하면서도 Controller의 가독성을 개선할 수 있습니다.

6. 결론

SpringDocs를 사용하여 Spring Boot 3.x에서 Swagger를 설정하는 방법을 살펴보았습니다. 기본적인 설정부터 어노테이션 사용, 그리고 코드 최적화를 위한 인터페이스 사용까지 다양한 방법을 통해 깔끔한 Swagger 문서를 작성할 수 있습니다.

참고

https://infinitecode.tistory.com/65