Spring Boot에서 Swagger로 API 문서 자동화하기

1. Swagger란?

Swagger는 RESTful API를 시각화하고 문서화하는 도구입니다.
Spring Boot 프로젝트에 적용하면, 별도의 문서 작성 없이 API 명세를 자동으로 생성할 수 있어 개발 및 협업 효율이 크게 올라갑니다.

---

2. Swagger 의존성 추가

Spring Boot 3.x 기준, springdoc-openapi 라이브러리를 사용합니다.

Maven 사용 시:

 

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

 

 

---

3. 기본 설정

보통 별도 설정 클래스 없이도 /swagger-ui.html 또는 /swagger-ui/index.html 로 접속하면 Swagger UI가 나타납니다.

예를 들어:

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

---

4. Swagger 설정 예제 (선택)

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration; 
@Configuration public class SwaggerConfig { 
@Bean public GroupedOpenApi publicApi() 
{ return GroupedOpenApi.builder() .group("public-api") .pathsToMatch("/api/**") .build(); 
}
}

---

5. 컨트롤러에 API 문서화 어노테이션 추가

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag; 
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "사용자 관련 API")
public class UserController {
@GetMapping("/{id}") @Operation(summary = "사용자 조회", description = "ID로 사용자 정보를 조회한다.") 
public User getUser(@PathVariable Long id)
{ return userService.getUserById(id); } }

---

6. 주요 기능

• 자동 API 명세 문서 생성
• 파라미터, 응답 모델 자동 추출
• API 테스트 기능 제공 (Swagger UI)
• 그룹핑, 보안 설정 가능

---

7. 마무리

Swagger는 빠르게 API 문서를 만들고 유지하는 데 매우 유용합니다.
프로젝트 초기부터 적용해두면, 개발자 및 클라이언트 모두에게 큰 도움이 됩니다.