[kotlog] 코프링으로 블로그 만들기 - 8 (Swagger)

dustle·2025년 6월 30일

kotlog

목록 보기

8/9

이번에는 Swagger 를 적용해보겠습니다.

Swagger 는 컨트롤러에 어노테이션만 붙이면 API 를 자동으로 문서화하고 시각화해주는 오픈소스 도구입니다.
각 API 를 버튼 클릭만으로 테스트할 수 있어서 개발할 때 굉장히 편리합니다.

build.gradle.kts

dependencies {
	implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9")
}

의존성은 아래 링크에서 최신 버전을 확인해 추가해주면 됩니다:
https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui

SwaggerConfig

문서에 제목과 설명을 추가하고 싶어서 config 클래스도 작성했습니다.

@OpenAPIDefinition(
    info = Info(
        title = "kotlog",
        description = "코프링으로 블로그 만들기",
        version = "v1.0"
    )
)

@Configuration
class SwaggerConfig

UserController

컨트롤러의 엔드포인트마다 @Operation 어노테이션을 붙여 API 설명도 달아주었습니다.

@RestController
@RequestMapping("/api/v1/users")
class UserController(
    val userRepository: UserRepository,
) {

    @GetMapping("/me")
    @Operation(summary = "내 정보 조회", description = "userId 를 기반으로 사용자 정보를 조회합니다.")
    fun me(userId: Long): ResponseEntity<UserResponse> {
        val user = userRepository.findById(userId)
            .orElseThrow { IllegalArgumentException("유저를 찾을 수 없습니다. id=$userId") }

        return ResponseEntity.ok(UserResponse.from(user))
    }
}

UserResponse DTO

DTO 에도 @Schema 어노테이션을 활용해 각 필드에 대한 설명과 예제를 달아주었습니다.

@Schema(description = "내 정보를 가져올 때의 응답 DTO")
data class UserResponse(
    @Schema(description = "사용자 id", example = "dustle1313")
    val username: String,

    @Schema(description = "사용자 email", example = "asdf@gmail.com")
    val email: String,

    @Schema(description = "사용자 nickname", example = "dustle")
    val nickname: String,
) {
    companion object {
        fun from(user: User): UserResponse = UserResponse(username = user.username, email = user.email, nickname = user.nickname)
    }
}