[Spring] 코틀린 + 스프링 부트 API, Swagger로 3분 만에 문서화하기 (springdoc-openapi)
안녕하세요! 이번 포스팅에서는 코틀린(Kotlin)과 스프링 부트(Spring Boot)로 개발한 API를 Swagger UI로 깔끔하게 문서화하는 가장 쉽고 현대적인 방법을 정리해 보려고 합니다.
예전에는 SpringFox를 많이 사용했지만, 스프링 부트 3.x 버전부터는 호환성 문제와 업데이트 중단 이슈로 인해 springdoc-openapi가 사실상의 표준이 되었습니다. 설정이 정말 간편해서, 한번 세팅해두면 앞으로의 프로젝트에서 두고두고 편하게 쓸 수 있습니다.
매번 기억하기 귀찮아서, 미래의 제가 다시 찾아볼 목적으로 작성하는 포스트입니다. 🚀
1. 의존성 추가: 딱 한 줄이면 끝!
가장 먼저 해야 할 일은 build.gradle.kts 파일에 springdoc-openapi 의존성을 추가하는 것입니다.
✅ build.gradle.kts (Kotlin DSL) 기준
Kotlin
dependencies {
// ... 다른 의존성들
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0") // 2.x 최신 버전 사용 권장
}✅ build.gradle (Groovy DSL) 사용 시
Groovy
dependencies {
// ... 다른 의존성들
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}의존성을 추가한 뒤, Gradle 프로젝트를 새로고침(Reload)하는 것을 잊지 마세요!
2. 실행하고 확인하기
놀랍게도, 이게 기본 설정의 전부입니다. 정말 간단하죠? 😄
이제 스프링 부트 애플리케이션을 실행하고, 웹 브라우저에서 아래 주소로 접속해 보세요.
Swagger UI 페이지: http://localhost:8080/swagger-ui.html
OpenAPI 명세서 (JSON): http://localhost:8080/v3/api-docs
포트 번호(8080)는 본인의 서버 설정에 맞게 변경해주세요.
접속하면 현재 프로젝트에 @RestController로 작성된 모든 API 목록이 자동으로 문서화된 것을 볼 수 있습니다.
3. API 문서에 생명 불어넣기 (Annotation)
자동 생성된 문서는 API의 존재 여부만 알려줄 뿐, 어떤 역할을 하고 어떤 값을 주고받아야 하는지는 알려주지 않습니다. 어노테이션(Annotation)을 사용하면 문서에 상세한 설명을 추가하여 동료 개발자(그리고 미래의 나)가 이해하기 쉬운 문서를 만들 수 있습니다.
📌 핵심 어노테이션 5가지
어노테이션 설명
@Tag API를 기능별로 그룹화합니다. (e.g., "사용자 API", "게시글 API")
@Operation API 하나의 기능(동작)을 설명합니다. (e.g., "사용자 정보 조회")
@Parameter 파라미터(매개변수)에 대한 설명과 제약조건을 추가합니다.
@ApiResponse API의 응답 상태(코드)별 시나리오를 설명합니다. (e.g., 200 성공, 404 실패)
@Schema DTO(데이터 모델)와 그 속성에 대한 설명을 추가합니다.
실제 코틀린 Controller에 어노테이션을 적용하면 아래와 같은 모습이 됩니다.
Kotlin
import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.Parameter
import io.swagger.v3.oas.annotations.media.Content
import io.swagger.v3.oas.annotations.media.Schema
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.tags.Tag
import org.springframework.web.bind.annotation.*
// --- DTO ---
@Schema(description = "사용자 정보 응답 DTO")
data class UserResponse(
@Schema(description = "사용자 고유 ID", example = "1")
val id: Long,
@Schema(description = "사용자 이름", example = "홍길동")
val name: String,
@Schema(description = "사용자 이메일", example = "gildong@example.com")
val email: String
)// --- Controller ---
@Tag(name = "User API", description = "사용자 관련 API 명세서입니다.")
@RestController
@RequestMapping("/api/users")
class UserController {
@Operation(summary = "ID로 사용자 정보 조회", description = "사용자 ID를 이용해 특정 사용자의 정보를 조회합니다.")
@ApiResponse(
responseCode = "200",
description = "조회 성공",
content = [Content(schema = Schema(implementation = UserResponse::class))]
)
@ApiResponse(responseCode = "404", description = "해당 ID의 사용자를 찾을 수 없습니다.")
@GetMapping("/{userId}")
fun getUserById(
@Parameter(description = "조회할 사용자의 ID", required = true, example = "1")
@PathVariable userId: Long
): UserResponse {
// 실제로는 DB에서 사용자 정보를 조회하는 로직이 들어갑니다.
return UserResponse(id = userId, name = "홍길동", email = "gildong@example.com")
}
}이렇게 수정한 뒤 다시 Swagger UI 페이지를 새로고침하면, 훨씬 풍부하고 유용한 API 문서를 확인할 수 있습니다.
4. 심화 과정: 더 깔끔한 문서를 위한 팁
- 팁 1: 문서 전역 정보 설정하기
application.yml 파일에서 문서의 제목, 버전, 전체 설명을 설정할 수 있습니다.
YAML
#### src/main/resources/application.yml
springdoc:
#### API 문서의 기본 정보 설정
info:
title: My Awesome Project API
description: 내 멋진 프로젝트의 API 명세서입니다. 많은 이용 부탁드립니다!
version: v1.0.0
#### Swagger UI 관련 설정
swagger-ui:
path: /swagger-ui.html # UI 접속 경로 (기본값)
display-request-duration: true # 요청 소요 시간 표시
groups-order: DESC # 태그 그룹 정렬 순서
operations-sorter: method # API 순서 정렬 기준 (알파벳, http-method)
- 팁 2: Spring Security와 함께 사용하기
만약 Spring Security를 사용 중이라면 Swagger 관련 경로에 접근 권한을 허용해주어야 합니다. 그렇지 않으면 403 Forbidden 에러를 만나게 됩니다.
SecurityConfig 파일에 아래 requestMatchers를 추가해주세요.
Kotlin
// SecurityConfig.kt
@Configuration
@EnableWebSecurity
class SecurityConfig {
@Bean
fun filterChain(http: HttpSecurity): SecurityFilterChain {
http
// ... 다른 시큐리티 설정 ...
.authorizeHttpRequests { auth ->
auth
// Swagger 관련 경로는 모두 허용
.requestMatchers(
"/swagger-ui/**",
"/v3/api-docs/**"
).permitAll()
.anyRequest().authenticated() // 나머지 요청은 인증 필요
}
// ...
return http.build()
}
}
마무리
springdoc-openapi를 이용하면 정말 간단한 설정만으로도 강력한 API 문서를 구축할 수 있습니다. 처음에는 조금 귀찮을 수 있지만, 어노테이션으로 설명을 잘 달아두면 나중에 협업할 때나 인수인계할 때, 그리고 미래의 내가 과거의 코드를 다시 볼 때 정말 큰 도움이 됩니다.
이제 동료 개발자나 미래의 나에게 욕먹지 않는(?) 깔끔한 API 문서를 만들 수 있습니다.
이번 포스팅이 도움이 되셨다면 좋겠습니다. 감사합니다!
