diff --git a/build.gradle b/build.gradle index ece8e565..7d1fc704 100644 --- a/build.gradle +++ b/build.gradle @@ -49,6 +49,9 @@ dependencies { // actuator implementation 'org.springframework.boot:spring-boot-starter-actuator' + + // SpringDoc OpenAPI (Swagger) + implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0' } tasks.named('test') { diff --git a/src/main/java/com/kamco/cd/kamcoback/config/api/ApiResponseDto.java b/src/main/java/com/kamco/cd/kamcoback/config/api/ApiResponseDto.java index eac190c4..2146a543 100644 --- a/src/main/java/com/kamco/cd/kamcoback/config/api/ApiResponseDto.java +++ b/src/main/java/com/kamco/cd/kamcoback/config/api/ApiResponseDto.java @@ -1,10 +1,12 @@ package com.kamco.cd.kamcoback.config.api; +import com.fasterxml.jackson.annotation.JsonIgnore; import com.fasterxml.jackson.annotation.JsonInclude; import com.kamco.cd.kamcoback.config.enums.EnumType; import lombok.Getter; import lombok.RequiredArgsConstructor; import lombok.ToString; +import org.springframework.http.HttpStatus; @Getter @ToString @@ -18,10 +20,17 @@ public class ApiResponseDto { @JsonInclude(JsonInclude.Include.NON_NULL) private T errorData; + @JsonIgnore private HttpStatus httpStatus = HttpStatus.OK; + public ApiResponseDto(T data) { this.data = data; } + private ApiResponseDto(T data, HttpStatus httpStatus) { + this.data = data; + this.httpStatus = httpStatus; + } + public ApiResponseDto(ApiResponseCode code) { this.error = new Error(code.getId(), code.getMessage()); } @@ -35,8 +44,17 @@ public class ApiResponseDto { this.errorData = errorData; } + // HTTP 상태 코드가 내장된 ApiResponseDto 반환 메서드들 public static ApiResponseDto createOK(T data) { - return new ApiResponseDto<>(data); + return new ApiResponseDto<>(data, HttpStatus.CREATED); + } + + public static ApiResponseDto ok(T data) { + return new ApiResponseDto<>(data, HttpStatus.OK); + } + + public static ApiResponseDto deleteOk(T data) { + return new ApiResponseDto<>(data, HttpStatus.NO_CONTENT); } public static ApiResponseDto createException(ApiResponseCode code) { diff --git a/src/main/java/com/kamco/cd/kamcoback/postgres/core/ZooCoreService.java b/src/main/java/com/kamco/cd/kamcoback/postgres/core/ZooCoreService.java index dd732435..c8092c7b 100644 --- a/src/main/java/com/kamco/cd/kamcoback/postgres/core/ZooCoreService.java +++ b/src/main/java/com/kamco/cd/kamcoback/postgres/core/ZooCoreService.java @@ -5,8 +5,12 @@ import com.kamco.cd.kamcoback.postgres.entity.ZooEntity; import com.kamco.cd.kamcoback.postgres.repository.ZooRepository; import com.kamco.cd.kamcoback.zoo.dto.ZooDto; import jakarta.persistence.EntityNotFoundException; +import java.util.List; +import java.util.Map; +import java.util.stream.Collectors; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; +import org.springframework.data.domain.PageImpl; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; @@ -56,10 +60,23 @@ public class ZooCoreService implements BaseCoreService search(ZooDto.SearchReq searchReq) { Page zooEntities = zooRepository.listZoo(searchReq); - return zooEntities.map(this::toDetailDto); + + // N+1 문제 해결: 한 번의 쿼리로 모든 Zoo의 animal count 조회 + List zooIds = + zooEntities.getContent().stream().map(ZooEntity::getUid).collect(Collectors.toList()); + + Map animalCountMap = zooRepository.countActiveAnimalsByZooIds(zooIds); + + // DTO 변환 + List details = + zooEntities.getContent().stream() + .map(zoo -> toDetailDtoWithCountMap(zoo, animalCountMap)) + .collect(Collectors.toList()); + + return new PageImpl<>(details, zooEntities.getPageable(), zooEntities.getTotalElements()); } - // Entity -> Detail DTO 변환 (동물 개수 포함) + // Entity -> Detail DTO 변환 (동물 개수 포함) - 단건 조회용 private ZooDto.Detail toDetailDto(ZooEntity zoo) { Long activeAnimalCount = zooRepository.countActiveAnimals(zoo.getUid()); return new ZooDto.Detail( @@ -72,4 +89,18 @@ public class ZooCoreService implements BaseCoreService Detail DTO 변환 (동물 개수 포함) - 배치 조회용 (N+1 해결) + private ZooDto.Detail toDetailDtoWithCountMap(ZooEntity zoo, Map countMap) { + Long activeAnimalCount = countMap.getOrDefault(zoo.getUid(), 0L); + return new ZooDto.Detail( + zoo.getUid(), + zoo.getUuid().toString(), + zoo.getName(), + zoo.getLocation(), + zoo.getDescription(), + zoo.getCreatedDate(), + zoo.getModifiedDate(), + activeAnimalCount); + } } diff --git a/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryCustom.java b/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryCustom.java index e053b4f0..51e17ebb 100644 --- a/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryCustom.java +++ b/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryCustom.java @@ -2,6 +2,8 @@ package com.kamco.cd.kamcoback.postgres.repository; import com.kamco.cd.kamcoback.postgres.entity.ZooEntity; import com.kamco.cd.kamcoback.zoo.dto.ZooDto; +import java.util.List; +import java.util.Map; import java.util.Optional; import org.springframework.data.domain.Page; @@ -14,4 +16,12 @@ public interface ZooRepositoryCustom { Optional getZooByUid(Long uid); Long countActiveAnimals(Long zooId); + + /** + * 여러 Zoo의 활성 동물 수를 한 번에 조회 (N+1 문제 해결) + * + * @param zooIds Zoo ID 목록 + * @return Map + */ + Map countActiveAnimalsByZooIds(List zooIds); } diff --git a/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryImpl.java b/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryImpl.java index 7d6ffa63..2dd41c02 100644 --- a/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryImpl.java +++ b/src/main/java/com/kamco/cd/kamcoback/postgres/repository/ZooRepositoryImpl.java @@ -7,7 +7,9 @@ import com.kamco.cd.kamcoback.zoo.dto.ZooDto; import com.querydsl.core.types.dsl.BooleanExpression; import com.querydsl.jpa.impl.JPAQuery; import com.querydsl.jpa.impl.JPAQueryFactory; +import java.util.HashMap; import java.util.List; +import java.util.Map; import java.util.Optional; import java.util.UUID; import lombok.RequiredArgsConstructor; @@ -75,6 +77,39 @@ public class ZooRepositoryImpl implements ZooRepositoryCustom { return count != null ? count : 0L; } + @Override + public Map countActiveAnimalsByZooIds(List zooIds) { + if (zooIds == null || zooIds.isEmpty()) { + return new HashMap<>(); + } + + // QueryDSL group by로 한 번에 조회 + List results = + queryFactory + .select(qAnimal.zoo.uid, qAnimal.count()) + .from(qAnimal) + .where(qAnimal.zoo.uid.in(zooIds), qAnimal.isDeleted.eq(false)) + .groupBy(qAnimal.zoo.uid) + .fetch(); + + // Map으로 변환 + Map countMap = new HashMap<>(); + for (com.querydsl.core.Tuple tuple : results) { + Long zooId = tuple.get(qAnimal.zoo.uid); + Long count = tuple.get(qAnimal.count()); + if (zooId != null && count != null) { + countMap.put(zooId, count); + } + } + + // 조회되지 않은 Zoo는 0으로 설정 + for (Long zooId : zooIds) { + countMap.putIfAbsent(zooId, 0L); + } + + return countMap; + } + private BooleanExpression nameContains(String name) { return name != null && !name.isEmpty() ? qZoo.name.contains(name) : null; } diff --git a/src/main/java/com/kamco/cd/kamcoback/zoo/AnimalApiController.java b/src/main/java/com/kamco/cd/kamcoback/zoo/AnimalApiController.java index 226de0d6..d3c5409e 100644 --- a/src/main/java/com/kamco/cd/kamcoback/zoo/AnimalApiController.java +++ b/src/main/java/com/kamco/cd/kamcoback/zoo/AnimalApiController.java @@ -1,15 +1,30 @@ package com.kamco.cd.kamcoback.zoo; +import com.kamco.cd.kamcoback.config.api.ApiResponseDto; import com.kamco.cd.kamcoback.zoo.dto.AnimalDto; +import com.kamco.cd.kamcoback.zoo.dto.AnimalDto.Basic; import com.kamco.cd.kamcoback.zoo.dto.AnimalDto.Category; import com.kamco.cd.kamcoback.zoo.dto.AnimalDto.Species; import com.kamco.cd.kamcoback.zoo.service.AnimalService; +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.responses.ApiResponses; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; -import org.springframework.http.HttpStatus; -import org.springframework.http.ResponseEntity; -import org.springframework.web.bind.annotation.*; +import org.springframework.web.bind.annotation.DeleteMapping; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RequestParam; +import org.springframework.web.bind.annotation.RestController; +@Tag(name = "Animal", description = "동물 관리 API") @RequiredArgsConstructor @RestController @RequestMapping({"/api/animals", "/v1/api/animals"}) @@ -23,10 +38,32 @@ public class AnimalApiController { * @param req 동물 생성 요청 * @return 생성된 동물 정보 */ + @Operation(summary = "동물 생성", description = "새로운 동물 정보를 등록합니다.") + @ApiResponses( + value = { + @ApiResponse( + responseCode = "201", + description = "동물 생성 성공", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = AnimalDto.Basic.class))), + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @PostMapping - public ResponseEntity createAnimal(@RequestBody AnimalDto.AddReq req) { + public ApiResponseDto createAnimal( + @io.swagger.v3.oas.annotations.parameters.RequestBody( + description = "동물 생성 요청 정보", + required = true, + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = AnimalDto.AddReq.class))) + @RequestBody + AnimalDto.AddReq req) { AnimalDto.Basic created = animalService.createAnimal(req); - return ResponseEntity.status(HttpStatus.CREATED).body(created); + return ApiResponseDto.createOK(created); } /** @@ -35,11 +72,30 @@ public class AnimalApiController { * @param uuid 동물 UUID * @return 동물 정보 */ + @Operation(summary = "동물 단건 조회", description = "UUID로 특정 동물의 상세 정보를 조회합니다.") + @ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "조회 성공", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = AnimalDto.Basic.class))), + @ApiResponse(responseCode = "404", description = "동물을 찾을 수 없음", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @GetMapping("/{uuid}") - public ResponseEntity getAnimal(@PathVariable String uuid) { + public ApiResponseDto getAnimal( + @Parameter( + description = "조회할 동물의 UUID", + required = true, + example = "550e8400-e29b-41d4-a716-446655440000") + @PathVariable + String uuid) { Long id = animalService.getAnimalByUuid(uuid); AnimalDto.Basic animal = animalService.getAnimal(id); - return ResponseEntity.ok(animal); + return ApiResponseDto.ok(animal); } /** @@ -48,11 +104,24 @@ public class AnimalApiController { * @param uuid 동물 UUID * @return 삭제 성공 메시지 */ + @Operation(summary = "동물 삭제", description = "UUID로 특정 동물을 삭제합니다 (논리 삭제).") + @ApiResponses( + value = { + @ApiResponse(responseCode = "204", description = "삭제 성공", content = @Content), + @ApiResponse(responseCode = "404", description = "동물을 찾을 수 없음", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @DeleteMapping("/{uuid}") - public ResponseEntity deleteAnimal(@PathVariable String uuid) { + public ApiResponseDto deleteAnimal( + @Parameter( + description = "삭제할 동물의 UUID", + required = true, + example = "550e8400-e29b-41d4-a716-446655440000") + @PathVariable + String uuid) { Long id = animalService.getAnimalByUuid(uuid); - animalService.deleteZoo(id); - return ResponseEntity.noContent().build(); + animalService.deleteAnimal(id); + return ApiResponseDto.deleteOk(uuid); } /** @@ -66,17 +135,40 @@ public class AnimalApiController { * @param sort 정렬 조건 (예: "name,asc") * @return 페이징 처리된 동물 목록 */ + @Operation( + summary = "동물 검색", + description = + "다양한 조건으로 동물을 검색하고 페이징된 결과를 반환합니다. 모든 검색 조건은 선택적이며, 조건 없이 호출하면 전체 동물 목록을 반환합니다.") + @ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "검색 성공", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = Page.class))), + @ApiResponse(responseCode = "400", description = "잘못된 검색 조건", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @GetMapping - public ResponseEntity> searchAnimals( - @RequestParam(required = false) String name, - @RequestParam(required = false) Category category, - @RequestParam(required = false) Species species, - @RequestParam(defaultValue = "0") int page, - @RequestParam(defaultValue = "20") int size, - @RequestParam(required = false) String sort) { + public ApiResponseDto> searchAnimals( + @Parameter(description = "동물 이름 (부분 일치 검색)", example = "호랑이") @RequestParam(required = false) + String name, + @Parameter(description = "서식지 카테고리", example = "MAMMAL") @RequestParam(required = false) + Category category, + @Parameter(description = "동물 종", example = "TIGER") @RequestParam(required = false) + Species species, + @Parameter(description = "페이지 번호 (0부터 시작)", example = "0") @RequestParam(defaultValue = "0") + int page, + @Parameter(description = "페이지 크기", example = "20") @RequestParam(defaultValue = "20") + int size, + @Parameter(description = "정렬 조건 (형식: 필드명,방향)", example = "name,asc") + @RequestParam(required = false) + String sort) { AnimalDto.SearchReq searchReq = new AnimalDto.SearchReq(name, category, species, page, size, sort); Page animals = animalService.search(searchReq); - return ResponseEntity.ok(animals); + return ApiResponseDto.ok(animals); } } diff --git a/src/main/java/com/kamco/cd/kamcoback/zoo/ZooApiController.java b/src/main/java/com/kamco/cd/kamcoback/zoo/ZooApiController.java index c1e24dac..ce4db8e1 100644 --- a/src/main/java/com/kamco/cd/kamcoback/zoo/ZooApiController.java +++ b/src/main/java/com/kamco/cd/kamcoback/zoo/ZooApiController.java @@ -1,13 +1,28 @@ package com.kamco.cd.kamcoback.zoo; +import com.kamco.cd.kamcoback.config.api.ApiResponseDto; import com.kamco.cd.kamcoback.zoo.dto.ZooDto; +import com.kamco.cd.kamcoback.zoo.dto.ZooDto.Detail; import com.kamco.cd.kamcoback.zoo.service.ZooService; +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.responses.ApiResponses; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; -import org.springframework.http.HttpStatus; -import org.springframework.http.ResponseEntity; -import org.springframework.web.bind.annotation.*; +import org.springframework.web.bind.annotation.DeleteMapping; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RequestParam; +import org.springframework.web.bind.annotation.RestController; +@Tag(name = "Zoo", description = "동물원 관리 API") @RequiredArgsConstructor @RestController @RequestMapping({"/api/zoos", "/v1/api/zoos"}) @@ -21,10 +36,32 @@ public class ZooApiController { * @param req 동물원 생성 요청 * @return 생성된 동물원 정보 (동물 개수 포함) */ + @Operation(summary = "동물원 생성", description = "새로운 동물원 정보를 등록합니다.") + @ApiResponses( + value = { + @ApiResponse( + responseCode = "201", + description = "동물원 생성 성공", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ZooDto.AddReq.class))), + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @PostMapping - public ResponseEntity createZoo(@RequestBody ZooDto.AddReq req) { + public ApiResponseDto createZoo( + @io.swagger.v3.oas.annotations.parameters.RequestBody( + description = "동물원 생성 요청 정보", + required = true, + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ZooDto.AddReq.class))) + @RequestBody + ZooDto.AddReq req) { ZooDto.Detail created = zooService.createZoo(req); - return ResponseEntity.status(HttpStatus.CREATED).body(created); + return ApiResponseDto.createOK(created); } /** @@ -33,11 +70,30 @@ public class ZooApiController { * @param uuid 동물원 UUID * @return 동물원 정보 (현재 동물 개수 포함) */ + @Operation(summary = "동물원 단건 조회", description = "UUID로 특정 동물원의 상세 정보를 조회합니다.") + @ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "조회 성공", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = ZooDto.Detail.class))), + @ApiResponse(responseCode = "404", description = "동물원을 찾을 수 없음", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @GetMapping("/{uuid}") - public ResponseEntity getZoo(@PathVariable String uuid) { + public ApiResponseDto getZoo( + @Parameter( + description = "조회할 동물원의 UUID", + required = true, + example = "550e8400-e29b-41d4-a716-446655440000") + @PathVariable + String uuid) { Long id = zooService.getZooByUuid(uuid); ZooDto.Detail zoo = zooService.getZoo(id); - return ResponseEntity.ok(zoo); + return ApiResponseDto.ok(zoo); } /** @@ -46,11 +102,24 @@ public class ZooApiController { * @param uuid 동물원 UUID * @return 삭제 성공 메시지 */ + @Operation(summary = "동물원 삭제", description = "UUID로 특정 동물원을 삭제합니다 (논리 삭제).") + @ApiResponses( + value = { + @ApiResponse(responseCode = "204", description = "삭제 성공", content = @Content), + @ApiResponse(responseCode = "404", description = "동물원을 찾을 수 없음", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @DeleteMapping("/{uuid}") - public ResponseEntity deleteZoo(@PathVariable String uuid) { + public ApiResponseDto deleteZoo( + @Parameter( + description = "삭제할 동물원의 UUID", + required = true, + example = "550e8400-e29b-41d4-a716-446655440000") + @PathVariable + String uuid) { Long id = zooService.getZooByUuid(uuid); zooService.deleteZoo(id); - return ResponseEntity.noContent().build(); + return ApiResponseDto.deleteOk(uuid); } /** @@ -63,15 +132,38 @@ public class ZooApiController { * @param sort 정렬 조건 (예: "name,asc") * @return 페이징 처리된 동물원 목록 (각 동물원의 현재 동물 개수 포함) */ + @Operation( + summary = "동물원 검색", + description = + "다양한 조건으로 동물원을 검색하고 페이징된 결과를 반환합니다. 모든 검색 조건은 선택적이며, 조건 없이 호출하면 전체 동물원 목록을 반환합니다.") + @ApiResponses( + value = { + @ApiResponse( + responseCode = "200", + description = "검색 성공", + content = + @Content( + mediaType = "application/json", + schema = @Schema(implementation = Page.class))), + @ApiResponse(responseCode = "400", description = "잘못된 검색 조건", content = @Content), + @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content) + }) @GetMapping - public ResponseEntity> searchZoos( - @RequestParam(required = false) String name, - @RequestParam(required = false) String location, - @RequestParam(defaultValue = "0") int page, - @RequestParam(defaultValue = "20") int size, - @RequestParam(required = false) String sort) { + public ApiResponseDto> searchZoos( + @Parameter(description = "동물원 이름 (부분 일치 검색)", example = "서울동물원") + @RequestParam(required = false) + String name, + @Parameter(description = "위치", example = "서울") @RequestParam(required = false) + String location, + @Parameter(description = "페이지 번호 (0부터 시작)", example = "0") @RequestParam(defaultValue = "0") + int page, + @Parameter(description = "페이지 크기", example = "20") @RequestParam(defaultValue = "20") + int size, + @Parameter(description = "정렬 조건 (형식: 필드명,방향)", example = "name,asc") + @RequestParam(required = false) + String sort) { ZooDto.SearchReq searchReq = new ZooDto.SearchReq(name, location, page, size, sort); Page zoos = zooService.search(searchReq); - return ResponseEntity.ok(zoos); + return ApiResponseDto.ok(zoos); } } diff --git a/src/main/java/com/kamco/cd/kamcoback/zoo/service/AnimalService.java b/src/main/java/com/kamco/cd/kamcoback/zoo/service/AnimalService.java index 72deb869..6b719586 100644 --- a/src/main/java/com/kamco/cd/kamcoback/zoo/service/AnimalService.java +++ b/src/main/java/com/kamco/cd/kamcoback/zoo/service/AnimalService.java @@ -36,7 +36,7 @@ public class AnimalService { * @param id 동물 ID */ @Transactional - public void deleteZoo(Long id) { + public void deleteAnimal(Long id) { zooCoreService.remove(id); }