Spring Boot와 OpenAPI로 강력한 REST API 만들기

Spring Boot와 OpenAPI로 강력한 REST API 만들기

Overview

Spring Boot는 Java 기반의 웹 애플리케이션을 쉽게 만들 수 있도록 도와주는 프레임워크입니다. OpenAPI는 RESTful API를 정의하고 문서화하는 데 사용되는 표준입니다. 이 두 가지를 함께 사용하면, 개발자는 효율적이고 잘 문서화된 API를 만들 수 있습니다. 이 글에서는 Spring Boot 애플리케이션에 OpenAPI를 통합하여 REST API를 정의하고 문서화하는 방법에 대해 자세히 설명하겠습니다.

1. Spring Boot 프로젝트 설정하기

Spring Boot 프로젝트를 시작하려면, 가장 먼저 Spring Initializr를 통해 기본 프로젝트 구조를 생성합니다. 이 과정은 웹 애플리케이션의 모든 기본 설정을 자동으로 해줍니다.

• Spring Initializr 접근하기: Spring Initializr

• 설정 항목:

• Project: Maven Project

• Language: Java

• Spring Boot: 현재 안정된 버전 (예: 3.0.0)

• Dependencies:

• Spring Web

• Spring Boot DevTools (개발 중 자동 재시작을 위해)

• Spring Data JPA (데이터베이스 접근을 위해)

• H2 Database (내장형 데이터베이스)

• Springdoc OpenAPI UI (OpenAPI 문서화를 위해)

위의 설정으로 프로젝트를 생성하고 ZIP 파일을 다운로드하여 압축을 해제합니다.

2. 기본 애플리케이션 구조

Spring Boot 애플리케이션의 기본 구조는 다음과 같습니다:

src
└── main
├── java
│   └── com
│       └── example
│           └── demo
│               ├── DemoApplication.java
│               ├── controller
│               │   └── UserController.java
│               └── model
│                   └── User.java
└── resources
└── application.properties

• DemoApplication.java: 애플리케이션의 진입점.
• UserController.java: REST API 엔드포인트 정의.
• User.java: 데이터 모델.

3. 데이터 모델 만들기

간단한 User 모델을 만들어 보겠습니다.

package com.example.demo.model;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class User {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;
private String name;
private String email;

// getters and setters
public Long getId() {
return id;
}

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

public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

public String getEmail() {
return email;
}

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

4. REST API 엔드포인트 구현

이제 UserController를 만들어 REST API 엔드포인트를 정의하겠습니다.

package com.example.demo.controller;

import com.example.demo.model.User;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

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

private List<User> users = new ArrayList<>();

@PostMapping
public ResponseEntity<User> createUser(@RequestBody User user) {
users.add(user);
return new ResponseEntity<>(user, HttpStatus.CREATED);
}

@GetMapping
public ResponseEntity<List<User>> getUsers() {
return new ResponseEntity<>(users, HttpStatus.OK);
}
}

5. OpenAPI 설정하기

OpenAPI 문서를 생성하기 위해 Springdoc OpenAPI를 설정합니다. pom.xml 파일에 아래와 같은 의존성을 추가합니다.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.6.14</version>
</dependency>

그런 다음, 기본 설정을 추가하여 OpenAPI 문서를 생성합니다. application.properties 파일에 다음을 추가합니다.

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

이제 /v3/api-docs로 접근하면 OpenAPI 문서 JSON을 확인할 수 있으며, /swagger-ui.html로 접근하면 Swagger UI를 통해 API 문서를 시각적으로 확인할 수 있습니다.

6. 에러 처리

API를 구현하다 보면 다양한 에러가 발생할 수 있습니다. 예를 들어, 잘못된 요청 본문을 보내는 경우 400 Bad Request 오류가 발생할 수 있습니다. 이 오류를 처리하기 위해 예외 처리기를 추가할 수 있습니다.

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestController;

@ControllerAdvice
@RestController
public class GlobalExceptionHandler {

@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleException(Exception e) {
return new ResponseEntity<>(e.getMessage(), HttpStatus.BAD_REQUEST);
}
}

이제 잘못된 요청이 들어올 경우, 클라이언트는 400 오류와 함께 에러 메시지를 받을 수 있습니다.

7. API 테스트하기

Postman과 같은 API 테스트 도구를 사용하여 구현한 API를 테스트할 수 있습니다. 다음은 Postman을 사용한 테스트 방법입니다.

1. POST 요청:

• URL: http://localhost:8080/api/users
• Body (JSON 형식):

  {
  "name": "John Doe",
  "email": "john@example.com"
  }

2. GET 요청:

• URL: http://localhost:8080/api/users
• 이 요청을 통해 저장된 사용자 목록을 확인할 수 있습니다.

8. 최종 확인

이제 Spring Boot와 OpenAPI를 활용하여 REST API를 성공적으로 구축했습니다. 이를 통해 개발자는 API 문서화와 유지보수의 효율성을 높일 수 있습니다.

참고 문서

• Spring Boot Documentation
• OpenAPI Specification
• Springdoc OpenAPI

이제 Spring Boot와 OpenAPI를 활용한 REST API 개발에 대해 잘 이해하셨을 것이라 생각합니다. 추가적인 질문이나 더 깊이 있는 설명이 필요하시다면 언제든지 물어보세요!