Spring Boot 3에서 Swagger와 H2 Database 사용하기

---

1. 들어가며

Spring Boot 3.x 프로젝트에서 Swagger를 이용한 API 문서화와 H2 Database를 활용해서 간단한 회원 관리 시스템 예시로 구현해보겠습니다. 이 글에서는 다음 내용을 다룰 예정입니다.

• Gradle을 이용한 프로젝트 설정
• Swagger UI 설정 및 사용법
• H2 Database 설정 및 JPA를 이용한 자동 테이블 생성
• 회원 관리 기능 (등록, 수정, 삭제) 구현

본 설명에서 사용하는 주요 기술 스택은 다음과 같습니다.

• Java 버전: 17
• Spring Boot 버전: 3.4.2
• Gradle 버전: 8.x (8.4 이상)
• H2 Database
• Swagger

---

2. 프로젝트 설정

먼저 build.gradle 파일을 다음과 같이 설정합니다.

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.4.2'
	id 'io.spring.dependency-management' version '1.1.7'
}

group = 'me.junu'
version = '0.0.1-SNAPSHOT'

java {
	toolchain {
		languageVersion = JavaLanguageVersion.of(17)
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.4.0'
	runtimeOnly 'com.h2database:h2'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
	useJUnitPlatform()
}

---

3. Swagger 설정

Swagger UI를 설정하기 위해 SwaggerConfig 클래스를 생성합니다.

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 customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("사용자 관리 API")
                .version("1.0")
                .description("Spring Boot 3.x (Springdoc) 사용자 관리 API"));
    }
}

---

3. H2 Database 설정

'application.yml' 파일에 H2 Database 설정을 추가합니다.

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password:
  h2:
    console:
      enabled: true
      path: /h2-console
  jpa:
    database-platform: org.hibernate.dialect.H2Dialect
    hibernate:
      ddl-auto: create-drop
    show-sql: true

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

---

3. 엔티티 클래스 생성

User 엔티티 클래스를 생성합니다.

import jakarta.persistence.*;

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String username;

    @Column(nullable = false)
    private String password;

    @Column(nullable = false)
    private String email;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

---

5. 리포지토리 인터페이스 생성

import me.junu.auth.user.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.Optional;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByUsername(String username);
}

---

6. 서비스 클래스 구현

import me.junu.auth.user.entity.User;
import me.junu.auth.user.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class UserService {
    private final UserRepository userRepository;

    @Autowired
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public User registerUser(User user) {
        return userRepository.save(user);
    }

    public User updateUser(Long id, User userDetails) {
        User user = userRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("User not found"));
        user.setUsername(userDetails.getUsername());
        user.setEmail(userDetails.getEmail());
        return userRepository.save(user);
    }

    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }

    public User loginUser(String username, String password) {
        User user = userRepository.findByUsername(username)
                .orElseThrow(() -> new RuntimeException("User not found"));
        // TODO: Add password verification
        return user;
    }
}

---

7. 컨트롤러 클래스 구현

import me.junu.auth.user.entity.User;
import me.junu.auth.user.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping("/register")
    public ResponseEntity<User> registerUser(@RequestBody User user) {
        User registeredUser = userService.registerUser(user);
        return ResponseEntity.ok(registeredUser);
    }

    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        User updatedUser = userService.updateUser(id, userDetails);
        return ResponseEntity.ok(updatedUser);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<?> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.ok().build();
    }
}

---

8. 애플리케이션 실행 및 테스트

1. 애플리케이션을 실행합니다.
2. Swagger UI (http://localhost:8080/swagger-ui.html)에 접속하여 API를 테스트합니다.
3. H2 Console (http://localhost:8080/h2-console)에 접속하여 데이터베이스를 확인합니다.

---

9. 마무리

이렇게 Spring Boot 3.x, Gradle, Swagger, H2 Database를 사용하여 간단한 회원 관리 API를 구현해보았습니다. 이 예제를 바탕으로 더 복잡한 기능을 추가하거나 실제 프로젝트에 적용해볼 수 있습니다. 주의할 점은 이 예제에서는 보안 처리나 예외 처리 등이 생략되어 있으므로, 실제 프로덕션 환경에서는 이러한 부분들을 반드시 고려해야 합니다.

---

auth.zip

0.17MB

---