Swagger는 API 설명에 대해 자동으로 문서화해주는 도구이다.
일반적으로 서버를 구축 후 프론트엔드 개발자나 모바일 개발자 등 나중에 다른 개발자들이 각 API 기능에 대해 어떤 역할을 하는지, 어떤 데이터를 보내야 하는지 어떤 결과가 나오는지에 대해 정보들을 구조적으로 보여주는 역할을 한다.
이에 코드 예시와 각 어노테이션이 어떤 역할을 하는지 설명을 하도록 하려고 한다.
🎯 코드 예시
@Operation(
summary = "이메일 중복 확인",
description = "user 테이블에 해당 이메일이 이미 등록되어 있는지 확인"
)
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "이메일 사용 가능 여부 반환 (true: 사용 가능, false: 사용 불가)"), // 200 OK 응답 추가
@ApiResponse(responseCode = "500", description = "서버 오류 발생") // 500 Internal Server Error 응답 추가 (예외 발생 시)
})
@GetMapping("/checkemail/{memEmail}")
public ResponseEntity<Boolean> checkmemEmail(@PathVariable(value="memEmail") String memEmail) {
Optional<User> existingUser = userRepository.findByMemEmail(memEmail);
boolean isAvailable = existingUser.isEmpty(); // 사용자 ID가 존재하지 않으면 사용 가능
return ResponseEntity.ok(isAvailable);
}예를 들어, 이메일 중복 확인이라는 handler 코드가 있을 때 관련 Swagger 역할을 하는 어노테이션은 다음과 같이 적용할 수 있다.
1. Tag
Tag는 여러 개의 API들을 관련성 있는 것끼리 묶어주는 역할을 한다.
예를 들어 회원가입, 로그인, 회원 정보 수정 같은 API들은 '회원 관련 API'로 묶고, 상품 조회, 상품 등록 같은 API들은 '상품 관련 API'로 묶는데, 이 때 프로젝트 규모가 커지고 API가 많아지면 @Tag 없이는 문서가 너무 복잡해져서 보기가 힘들어진다.
2. Operation
Operation은 API 하나하나(@GetMapping, @PostMapping 등으로 정의된 메소드)가 어떤 기능을 하는지, 목적이 뭔지 간략하게 설명해주는 역할을 한다.
summary는 API 목록에서 바로 보이는 짧은 제목,description은 API를 클릭했을 때 나오는 더 자세한 설명이다. 입력 파라미터나 반환 값에 대한 설명도 추가할 수 있어서 API 사용법을 명확하게 알려주는 이점이 있다.
Responses & ApiResponse
ApiResponses는 특정 API가 보낼 수 있는 가능한 모든 응답들을 모아두는 곳이고, 그 안에 들어가는 @ApiResponse 하나하나가 특정 응답 코드(예: 200, 400, 500)에 대한 설명이다. 이를 사용함으로써 API를 사용하는 쪽에서는 API 호출 결과로 어떤 응답 코드들을 받을 수 있는지, 그리고 각 코드별로 응답 본문이 어떻게 생겼는지 미리 파악할 수 있으며, 응답을 처리하는 코드를 더 정확하게 작성 할 수 있는 이점이 있다.
Epilogue
결론적으로
@Tag, @Operation, @ApiResponses같은 어노테이션들을 사용해서스웨거로 API 문서를 만드는 작업은 여러분의 API를 "설명하기 쉽고, 사용하기 편리하고, 관리하기 용이하게" 만들어주는 아주 중요한 과정이며, 협업에서 개발자들 간에 소통 및 개발 속도 등 향상을 위한 중요한 작업이다.
