Spring Boot 프로젝트에 Swagger UI 적용하여 API 문서 자동 생성하기: 상세 가이드

Spring Boot 프로젝트에서 RESTful API를 개발할 때, API 문서를 작성하는 것은 필수적인 작업입니다. 잘 정돈된 API 문서는 개발팀 간의 협업을 원활하게 하고, API를 사용하는 다른 개발자들에게 명확한 정보를 제공하여 개발 생산성을 향상시킵니다. Swagger UI는 이러한 API 문서를 자동으로 생성하고 시각적으로 제공하는 강력한 도구입니다. 이 글에서는 Spring Boot 프로젝트에 Swagger UI를 적용하는 방법과, 각 코드의 의미를 상세히 설명하며 실제 예제를 통해 이해를 돕겠습니다.

728x90

 

아래는 위 Swagger 주석과 API 구현을 Spring Boot로 변환한 예제입니다. Spring Boot에서는 주로 Springdoc OpenAPI를 사용하여 Swagger 문서를 생성합니다. 이를 기반으로 변환한 코드입니다.

---

Spring Boot 변환 코드

1. Spring Boot Dependencies

먼저, pom.xml에 필요한 의존성을 추가합니다:

<dependencies>
    <!-- Spring Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Springdoc OpenAPI -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.7.0</version>
    </dependency>
</dependencies>

---

2. User 엔티티

package com.example.demo.model;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "사용자 데이터를 나타내는 스키마")
public class User {

    @Schema(description = "사용자의 고유 식별자", example = "1")
    private Integer id;

    @Schema(description = "사용자의 이름", example = "이홍석")
    private String name;

    @Schema(description = "사용자의 이메일 주소", example = "ihongsoeg@example.com")
    private String email;
}

---

3. UserController 작성

package com.example.demo.controller;

import com.example.demo.model.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

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

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

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

    public UserController() {
        users.add(new User(1, "이홍석", "ihongsoeg@example.com"));
        users.add(new User(2, "김철수", "cheolsu@example.com"));
        users.add(new User(3, "박영희", "younghee@example.com"));
    }

    @Operation(summary = "사용자 목록 조회", description = "모든 사용자의 목록을 반환합니다.")
    @GetMapping
    public ResponseEntity<List<User>> getAllUsers() {
        return ResponseEntity.ok(users);
    }

    @Operation(summary = "특정 사용자 조회", description = "특정 ID를 가진 사용자의 정보를 반환합니다.")
    @GetMapping("/{id}")
    public ResponseEntity<?> getUserById(
            @PathVariable @Schema(description = "사용자의 고유 식별자", example = "1") Integer id) {
        Optional<User> user = users.stream().filter(u -> u.getId().equals(id)).findFirst();
        return user.map(ResponseEntity::ok)
                   .orElseGet(() -> ResponseEntity.status(404).body("User not found"));
    }

    @Operation(summary = "사용자 생성", description = "새로운 사용자를 생성합니다.")
    @PostMapping
    public ResponseEntity<User> createUser(
            @RequestBody @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "생성할 사용자 데이터") User newUser) {
        users.add(newUser);
        return ResponseEntity.status(201).body(newUser);
    }
}

---

728x90

4. Swagger 문서 확인

Spring Boot 앱을 실행한 후, 기본적으로 http://localhost:8080/swagger-ui.html 에서 Swagger UI를 확인할 수 있습니다.

---

주요 포인트

• Swagger 어노테이션: @Operation, @Schema, @RequestBody를 활용하여 문서화.
• Springdoc OpenAPI: Spring Boot 프로젝트에서 Swagger 문서를 생성 및 관리.
• 유연한 JSON 데이터 처리: Spring의 내장 Jackson 라이브러리를 통해 JSON 직렬화/역직렬화 지원.

필요에 따라 추가적인 설정이나 커스터마이징도 가능합니다. 😊