Spring Boot와 Swagger 통합 가이드

Spring Boot와 Swagger 통합 가이드

Overview

Spring Boot는 빠르게 애플리케이션을 구축할 수 있는 강력한 프레임워크이며, Swagger는 API 문서화와 테스트를 쉽게 할 수 있도록 도와주는 도구입니다. 이 두 가지를 함께 사용하면 API의 문서를 자동으로 생성하고, 테스트를 간편하게 할 수 있는 강력한 환경을 구축할 수 있습니다. 이번 글에서는 Spring Boot와 Swagger를 통합하는 방법을 상세히 설명하겠습니다.

Spring Boot와 Swagger 통합 과정

1. Spring Boot 프로젝트 설정

먼저, Spring Boot 프로젝트를 설정해야 합니다. Spring Initializr를 사용하면 필요한 종속성을 쉽게 추가할 수 있습니다. 아래는 기본적인 설정 방법입니다.

1. Spring Initializr 접근

• Spring Initializr에 접속합니다.

2. 프로젝트 메타데이터 설정

• Project는 Maven Project 또는 Gradle Project 중 선택합니다.
• Language는 Java를 선택합니다.
• Spring Boot 버전을 선택합니다.
• Project Metadata에서 Group과 Artifact를 입력합니다.
• Dependencies에서 Spring Web, Spring Data JPA 등을 선택할 수 있습니다.

3. 프로젝트 생성 및 다운로드

• Generate 버튼을 클릭하여 프로젝트를 생성하고 다운로드합니다.
• 다운로드한 ZIP 파일을 추출한 후, IDE(예: IntelliJ IDEA, Eclipse)에서 프로젝트를 엽니다.

2. Swagger 의존성 추가

Swagger를 사용하기 위해서는 springfox-swagger2와 springfox-swagger-ui 라이브러리를 추가해야 합니다. Gradle 또는 Maven을 사용하여 의존성을 추가할 수 있습니다.

Maven을 사용하는 경우

pom.xml 파일에 다음 의존성을 추가합니다:

<dependencies>
  <!-- 기존 의존성들... -->

  <!-- Swagger 의존성 추가 -->
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
  </dependency>
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
  </dependency>
</dependencies>

Gradle을 사용하는 경우

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

dependencies {
// 기존 의존성들...

// Swagger 의존성 추가
implementation 'io.springfox:springfox-swagger2:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'
}

3. Swagger 설정 클래스 추가

Swagger를 사용할 수 있도록 설정 클래스를 추가해야 합니다. 이 클래스는 Swagger의 설정을 정의합니다. SwaggerConfig라는 클래스를 생성하고 다음과 같이 설정합니다:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build();
}
}

• @Configuration 어노테이션을 사용하여 이 클래스가 Spring의 설정 클래스로 사용됨을 선언합니다.
• Docket 객체를 생성하고 API 문서화의 기본 설정을 정의합니다. apis(RequestHandlerSelectors.basePackage("com.example.controller"))를 통해 Swagger가 문서화할 컨트롤러의 패키지를 지정합니다.

4. 컨트롤러 작성

Swagger가 문서화할 API를 생성합니다. 예를 들어, 간단한 REST 컨트롤러를 작성해보겠습니다:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class SampleController {

@GetMapping("/hello")
public String sayHello() {
return "Hello, World!";
}
}

이 컨트롤러는 /api/hello 경로에서 "Hello, World!"를 반환하는 간단한 GET 요청 핸들러를 포함하고 있습니다.

5. 애플리케이션 실행 및 Swagger UI 확인

애플리케이션을 실행하고 Swagger UI를 확인합니다. 기본적으로 Swagger UI는 /swagger-ui/ 경로에서 접근할 수 있습니다. 예를 들어, 브라우저에서 http://localhost:8080/swagger-ui/로 접근하면 Swagger UI를 통해 API 문서를 시각적으로 확인할 수 있습니다.

6. 에러 처리

에러 코드 및 해결 방법

• 404 Not Found: Swagger UI 페이지를 찾을 수 없다는 에러가 발생하는 경우, Swagger 설정이 제대로 되어 있는지 확인합니다. SwaggerConfig 클래스가 제대로 설정되어 있는지, 의존성이 제대로 추가되었는지 점검합니다.

• 500 Internal Server Error: 서버에서 오류가 발생한 경우, 애플리케이션의 로그를 확인하여 어떤 오류가 발생했는지 파악합니다. 흔히 발생할 수 있는 문제는 Springfox 버전의 호환성 문제일 수 있으므로, 버전을 확인하고 호환되는 버전으로 업데이트합니다.

참고문서

• Spring Boot 공식 문서
• Swagger 공식 문서
• Springfox GitHub 저장소
• Springfox Swagger2 의존성 문서

이 가이드를 통해 Spring Boot 애플리케이션에 Swagger를 통합하여 API 문서를 자동으로 생성하고, 시각적으로 검토할 수 있는 환경을 구축할 수 있습니다.