🚀 RESTful API 설계 가이드 (Spring Data JPA + Swagger)

✅ 서론 - RESTful API란 무엇인가? 왜 사용하는가?
✅ 본론 - Spring Boot와 JPA를 활용한 RESTful API 설계
✅ 본론 - Swagger를 사용한 API 문서화
✅ 결론 - RESTful API 설계 베스트 프랙티스 및 확장 방향

---

1️⃣ 서론: RESTful API란 무엇인가? 왜 사용하는가?

🔹 RESTful API란?

• **REST (Representational State Transfer)**는 HTTP 프로토콜을 기반으로 자원을 주고받는 아키텍처 스타일이야.
• URL로 자원을 식별하고, HTTP 메서드(GET, POST, PUT, DELETE)로 자원에 대한 행위를 정의.
• JSON 포맷으로 데이터를 주고받으며, 클라이언트-서버 구조로 구성.

🔹 왜 RESTful API를 사용하는가?

✅ 서버와 클라이언트의 역할이 명확 → **프론트엔드(React, Vue.js)**와 **백엔드(Spring Boot)**의 분리
✅ 확장성 & 유연성 → 다양한 클라이언트(웹, 모바일, IoT)에서 사용 가능
✅ 재사용성 → 동일한 API를 여러 프로젝트에서 재사용 가능

🔥 Spring Boot는 RESTful API를 빠르고 효율적으로 설계할 수 있는 강력한 프레임워크!
이제 Spring Data JPA와 Swagger를 사용하여 RESTful API를 설계해보자.

---

2️⃣ Spring Boot와 JPA를 활용한 RESTful API 설계

🔹 프로젝트 환경 설정 및 기본 구성

📌 build.gradle 또는 pom.xml에 다음 의존성 추가

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'
    runtimeOnly 'com.h2database:h2'  // H2 Database 사용
}

🔹 데이터베이스 설정 (H2 Database)

📌 application.properties

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=
spring.h2.console.enabled=true
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.H2Dialect

 

• H2 콘솔 URL: http://localhost:8080/h2-console
• 테스트용 In-memory DB로 개발 속도 향상

---

🔹 Entity 설계 (Post Entity)

📌 Post.java

package com.example.demo.model;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

@Entity
@Getter
@Setter
@NoArgsConstructor
public class Post {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;
    private String content;
}

 

 

• @Entity: JPA가 관리하는 객체
• @Id + @GeneratedValue: 기본 키(PK)와 자동 생성
• Lombok을 사용하여 Getter, Setter, 기본 생성자 자동 생성

---

 

 

🔹 Repository 설계 (PostRepository)

📌 PostRepository.java

package com.example.demo.repository;

import com.example.demo.model.Post;
import org.springframework.data.jpa.repository.JpaRepository;

public interface PostRepository extends JpaRepository<Post, Long> {
}

Spring Data JPA 사용 → CRUD 메서드 자동 생성 (findAll, save, findById, deleteById)

---

🔹 Service 설계 (PostService)

📌 PostService.java

package com.example.demo.service;

import com.example.demo.model.Post;
import com.example.demo.repository.PostRepository;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class PostService {
    private final PostRepository postRepository;

    public PostService(PostRepository postRepository) {
        this.postRepository = postRepository;
    }

    public List<Post> getAllPosts() {
        return postRepository.findAll();
    }

    public Post getPostById(Long id) {
        return postRepository.findById(id).orElse(null);
    }

    public Post createPost(Post post) {
        return postRepository.save(post);
    }

    public Post updatePost(Long id, Post updatedPost) {
        Post post = postRepository.findById(id).orElse(null);
        if (post != null) {
            post.setTitle(updatedPost.getTitle());
            post.setContent(updatedPost.getContent());
            return postRepository.save(post);
        }
        return null;
    }

    public void deletePost(Long id) {
        postRepository.deleteById(id);
    }
}

---

🔹 Controller 설계 (PostController)

📌 PostController.java

package com.example.demo.controller;

import com.example.demo.model.Post;
import com.example.demo.service.PostService;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/posts")
public class PostController {
    private final PostService postService;

    public PostController(PostService postService) {
        this.postService = postService;
    }

    @GetMapping
    public List<Post> getAllPosts() {
        return postService.getAllPosts();
    }

    @GetMapping("/{id}")
    public Post getPostById(@PathVariable Long id) {
        return postService.getPostById(id);
    }

    @PostMapping
    public Post createPost(@RequestBody Post post) {
        return postService.createPost(post);
    }

    @PutMapping("/{id}")
    public Post updatePost(@PathVariable Long id, @RequestBody Post post) {
        return postService.updatePost(id, post);
    }

    @DeleteMapping("/{id}")
    public void deletePost(@PathVariable Long id) {
        postService.deletePost(id);
    }
}

---

3️⃣ Swagger를 사용한 API 문서화

🔹 Swagger 설정 (SpringDoc OpenAPI 사용)

📌 application.properties

springdoc.swagger-ui.path=/swagger-ui.html

 

📌 SwaggerConfig.java

package com.example.demo.config;

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.0")
                .description("Spring Boot RESTful API 예제"));
    }
}

 

📌 Swagger UI 접근 URL

http://localhost:8080/swagger-ui.html

✅ Swagger UI를 통해 API 문서 자동 생성 및 테스트 가능!

---

4️⃣ 결론: RESTful API 설계 베스트 프랙티스 및 확장 방향

🔹 베스트 프랙티스

✅ RESTful URI 설계 → 명사 사용, 소문자 사용 (/api/posts, /api/posts/{id})
✅ HTTP 메서드 사용 → GET, POST, PUT, DELETE 적절히 사용
✅ 상태 코드 응답 → 200 OK, 201 Created, 404 Not Found, 400 Bad Request

🔹 확장 방향

✅ Spring Security + JWT 인증 → 보안 강화
✅ 페이징 및 정렬 (Pageable)
✅ 예외 처리 및 Global Exception Handler
✅ CI/CD 및 배포 (AWS, Docker)

🚀 이제 Spring Boot와 Swagger를 활용하여 RESTful API를 설계하고, 블로그에 연재해보자!