TIL - 20260204

0204 스프링 부트 프로젝트 (6/N): API 문서화(Swagger)와 파일 업로드(S3)

---

✅ 1. Swagger (OpenAPI): API 문서 자동화

• Swagger는 OpenAPI Specification(OAS) 표준을 기반으로, REST API의 명세를 자동으로 생성하고, 시각적인 UI로 문서화하며, 해당 UI에서 직접 API를 테스트해볼 수 있는 강력한 도구입니다.

• 문제점: API를 개발한 후, API 명세서를 별도의 문서(Wiki, Excel 등)로 관리하면, 코드 변경 사항이 문서에 제때 반영되지 않아 결국 코드와 문서가 불일치하게 되는 문제가 발생합니다.

• Swagger의 해결책: 코드가 곧 문서(Code as Documentation)가 되도록 합니다. 코드에 추가한 어노테이션을 기반으로 항상 최신 상태의 API 문서를 자동으로 생성해줍니다.

➕ springdoc-openapi를 이용한 설정

1. 의존성 추가 (build.gradle):

   dependencies {
       implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
   }

2. 접속 및 확인:

   • 의존성 추가 후 애플리케이션을 실행하기만 하면, 별도의 설정 없이도 다음 경로에서 API 문서를 확인할 수 있습니다.
     • Swagger UI: http://localhost:8080/swagger-ui.html
     • API 명세 (JSON): http://localhost:8080/v3/api-docs

➕ 주요 어노테이션으로 문서 상세화

• 컨트롤러와 DTO에 어노테이션을 추가하여, 자동 생성된 문서의 가독성과 상세함을 높일 수 있습니다.
  • @Tag: 컨트롤러 그룹(태그)에 대한 설명을 추가.
  • @Operation: 각 API 엔드포인트의 기능에 대한 요약(summary) 및 설명(description)을 추가.
  • @Schema: DTO나 모델 객체의 필드에 대한 설명을 추가.

@Tag(name = "Post API", description = "게시글 관련 API")
@RestController
@RequestMapping("/api/posts")
public class PostController {

    @Operation(summary = "게시글 생성", description = "새로운 게시글을 등록합니다.")
    @PostMapping
    public ResponseEntity<Void> createPost(@RequestBody PostCreateRequest request) {
        // ...
    }
}

@Schema(description = "게시글 생성 요청 DTO")
public class PostCreateRequest {
    @Schema(description = "게시글 제목", example = "스프링 부트 강좌")
    private String title;
    // ...
}

---

✅ 2. AWS S3 (Simple Storage Service)를 이용한 파일 업로드

• 사용자가 업로드하는 이미지, 동영상 등의 정적 파일(Static File)을 애플리케이션 서버(EC2)에 직접 저장하는 것은 여러 문제점을 야기합니다.

  • 서버의 디스크 용량을 차지하고, 서버를 확장(Scale-out)할 때 파일 동기화 문제가 발생합니다.
  • 서버에 부하를 줍니다.

• AWS S3: 이러한 문제를 해결하기 위해, 파일 저장을 전담하는 객체 스토리지(Object Storage) 서비스인 S3를 사용하는 것이 표준적인 방법입니다.

➕ AWS SDK 및 S3 연동 설정

1. 의존성 추가 (build.gradle): AWS SDK for Java v2를 사용하기 위한 의존성을 추가합니다.

   dependencies {
       implementation 'software.amazon.awssdk:s3:2.20.43'
   }

2. application.yml 설정: AWS 자격 증명(Access Key, Secret Key)과 S3 버킷 정보를 설정합니다.

   cloud:
     aws:
       credentials:
         access-key: YOUR_ACCESS_KEY
         secret-key: YOUR_SECRET_KEY
       region:
         static: ap-northeast-2
       s3:
         bucket: your-s3-bucket-name

   • 보안: 실제 운영 환경에서는 자격 증명을 설정 파일에 직접 작성하는 대신, IAM Role이나 환경 변수를 사용하는 것이 훨씬 안전합니다.

3. S3 클라이언트 Bean 등록: S3와 통신할 S3Client 객체를 Spring Bean으로 등록하는 설정 클래스를 작성합니다.

---

✅ 3. 파일 업로드 로직 구현

1. Controller:

   • 파일 업로드는 multipart/form-data 형식의 요청으로 처리됩니다.
   • @RequestPart 어노테이션을 사용하여 MultipartFile 객체로 업로드된 파일을 받습니다.

2. Service:

   • MultipartFile 객체로부터 파일의 원본 이름, 크기, InputStream 등을 얻습니다.
   • 파일 이름이 중복되지 않도록 UUID 등을 사용하여 고유한 파일 이름을 생성합니다.
   • S3Client의 putObject() 메서드를 사용하여, 파일을 S3 버킷에 업로드합니다.
   • 업로드가 완료되면, S3에 저장된 파일에 접근할 수 있는 URL을 생성합니다.
   • 이 파일 URL을 데이터베이스의 엔티티에 저장하여, 나중에 파일을 조회할 수 있도록 합니다.

// FileUploadController.java
@RestController
public class FileUploadController {
    private final FileUploadService fileUploadService;

    @PostMapping("/api/upload")
    public ResponseEntity<String> uploadFile(@RequestPart("file") MultipartFile file) {
        String fileUrl = fileUploadService.uploadFile(file);
        return ResponseEntity.ok(fileUrl);
    }
}

// FileUploadService.java
@Service
public class FileUploadService {
    private final S3Client s3Client;
    private final String bucketName;

    public String uploadFile(MultipartFile file) {
        String uniqueFileName = UUID.randomUUID().toString() + "_" + file.getOriginalFilename();
        
        try {
            s3Client.putObject(PutObjectRequest.builder()
                            .bucket(bucketName)
                            .key(uniqueFileName)
                            .build(),
                    RequestBody.fromInputStream(file.getInputStream(), file.getSize()));

            // 업로드된 파일의 URL 반환
            return s3Client.utilities().getUrl(builder -> builder.bucket(bucketName).key(uniqueFileName)).toString();

        } catch (IOException e) {
            throw new RuntimeException("파일 업로드 실패", e);
        }
    }
}

---

📌 요약

• Swagger (springdoc-openapi)는 컨트롤러 코드의 어노테이션을 기반으로 API 문서를 자동으로 생성하고 테스트 UI를 제공하여, 개발자 간의 협업 효율을 극대화합니다.
• 사용자가 업로드하는 파일은 애플리케이션 서버가 아닌, AWS S3와 같은 객체 스토리지에 저장하여 서버의 부하를 줄이고 확장성을 확보해야 합니다.
• Spring Boot에서 파일 업로드는 MultipartFile 객체로 처리하며, AWS SDK의 S3Client를 사용하여 S3 버킷에 파일을 업로드하고, 그 결과로 얻은 파일 URL을 DB에 저장하는 방식으로 구현합니다.