[Concert] 공연 목록 조회 보강, Swagger 문서화 보강

src/main/java/com/back/web7_9_codecrete_be/domain/concerts/controller/ConcertAdminController.java

@@ -35,16 +35,27 @@ public RsData<SetResultResponse> setConcert() throws InterruptedException {
         return RsData.success(kopisApiService.setConcertsList());
     }
 
-    @Operation(summary = "공연 정보 갱신",description = "공연 정보를 직접 갱신합니다.")
+    @Operation(summary = "공연 정보 갱신", description = "공연 정보를 직접 갱신합니다.")
     @PatchMapping("updateConcert/{concertId}")
     public RsData<ConcertItem> updateConcert(
-            @Schema(description = "갱신 대상이 될 공연의 ID 값입니다.")
-            @PathVariable Long concertId,
-            @Schema(description = "갱신 내용입니다.")
-            @RequestBody ConcertUpdateRequest concertUpdateRequest
-    ){
+            @PathVariable
+            @Schema(description = """
+                    <h3>갱신 대상이 될 공연의 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값입니다. <br/>
+                    <strong>/updateConcert/{concertId}</strong> 형태로 요청하면 됩니다.
+                    """)
+            Long concertId,
+            @RequestBody
+            @Schema(description = """
+                    <h3>공연 갱신 요청 정보입니다.</h3>
+                    <hr/>
+                    공연의 제목, 설명 등 수정이 필요한 정보들을 전달합니다.
+                    """)
+            ConcertUpdateRequest concertUpdateRequest
+    ) {
         ConcertItem concertItem = concertService.updateConcert(concertId, concertUpdateRequest);
-        return RsData.success("공연 정보 수정이 완료되었습니다.",concertItem);
+        return RsData.success("공연 정보 수정이 완료되었습니다.", concertItem);
     }
 
     @Operation(summary = "예매 시간이 없는 공연 목록 조회", description = "예매 시간이 없는 공연들을 공연시간 내림차순으로 출력합니다.")
@@ -58,25 +69,46 @@ public List<ConcertItem> getNoTicketTimeConcertsList(
 
     @Operation(summary = "공연을 삭제합니다.", description = "해당 공연을 삭제합니다.")
     @DeleteMapping("deleteConcert/{concertId}")
-    public RsData<Void> deleteConcert(@PathVariable Long concertId){
+    public RsData<Void> deleteConcert(
+            @PathVariable
+            @Schema(description = """
+                    <h3>삭제 대상이 될 공연의 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값입니다. <br/>
+                    <strong>/deleteConcert/{concertId}</strong> 형태로 요청하면 됩니다.
+                    """)
+            Long concertId
+    ) {
         concertService.deleteConcert(concertId);
-        return RsData.success("공연 정보 삭제에 성공하였습니다.",null);
+        return RsData.success("공연 정보 삭제에 성공하였습니다.", null);
     }
 
-    @Operation(summary = "예매 시간 등록",description = "개별 공연에 대한 예매 시간을 설정합니다.")
+    @Operation(summary = "예매 시간 등록", description = "개별 공연에 대한 예매 시간을 설정합니다.")
     @PatchMapping("ticketTimeSet")
-    public RsData<ConcertDetailResponse>  ticketTimeSet(
-            @RequestBody ConcertTicketTimeSetRequest concertTicketTimeSetRequest
-    ){
+    public RsData<ConcertDetailResponse> ticketTimeSet(
+            @RequestBody
+            @Schema(description = """
+                    <h3>공연 예매 시간 설정 정보입니다.</h3>
+                    <hr/>
+                    공연 ID와 예매 시작 시간 정보를 전달합니다.
+                    """)
+            ConcertTicketTimeSetRequest concertTicketTimeSetRequest
+    ) {
         return RsData.success(concertService.setConcertTime(concertTicketTimeSetRequest));
     }
 
-    @Operation(summary = "개별 공연 API통한 갱신",description = "개별 공연에 대해서 공연 예술 통합망(Kopis)을 통해 데이터를 조회하고 해당 데이터를 갱신합니다.")
+    @Operation(summary = "개별 공연 API통한 갱신", description = "개별 공연에 대해서 공연 예술 통합망(Kopis)을 통해 데이터를 조회하고 해당 데이터를 갱신합니다.")
     @PatchMapping("updateConcertByKopisAPI/{concertId}")
     public RsData<ConcertDetailResponse> updateConcertByKopisAPI(
-            @Schema(description = "갱신 대상이 될 공연의 ID 값입니다.")
-            @PathVariable Long concertId
-    ){
+            @PathVariable
+            @Schema(description = """
+                    <h3>갱신 대상이 될 공연의 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값입니다. <br/>
+                    <strong>/updateConcertByKopisAPI/{concertId}</strong> 형태로 요청하면 됩니다.
+                    """)
+            Long concertId
+    ) {
         kopisApiService.concertUpdateByKopisApi(concertId);
         return RsData.success(concertService.getConcertDetail(concertId));
     }

src/main/java/com/back/web7_9_codecrete_be/domain/concerts/controller/ConcertController.java

@@ -5,6 +5,7 @@
 import com.back.web7_9_codecrete_be.domain.concerts.dto.concert.ConcertDetailResponse;
 import com.back.web7_9_codecrete_be.domain.concerts.dto.concert.ConcertItem;
 import com.back.web7_9_codecrete_be.domain.concerts.dto.concert.ConcertLikeResponse;
+import com.back.web7_9_codecrete_be.domain.concerts.dto.concert.ListSort;
 import com.back.web7_9_codecrete_be.domain.concerts.dto.ticketOffice.TicketOfficeElement;
 import com.back.web7_9_codecrete_be.domain.concerts.entity.TicketOffice;
 import com.back.web7_9_codecrete_be.domain.concerts.service.ConcertService;
@@ -37,68 +38,85 @@ public class ConcertController {
     private final ConcertService concertService;
     private final Rq rq;
 
-    @Operation(summary = "공연목록", description = "공연 전체 목록을 조회합니다. 시작일자를 기준으로 오름차순 조회합니다.")
-    @GetMapping("list")
-    public RsData<List<ConcertItem>> getList (
-            @Schema(description = "페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.")
-            Pageable pageable
-    ) {
-        return RsData.success(concertService.getConcertsList(pageable));
-    }
-
-    @Operation(summary = "다가오는 공연 목록", description = "오늘을 기준으로 다가오는 공연 목록을 조회합니다.")
-    @GetMapping("upComingList")
-    public RsData<List<ConcertItem>> getUpComingList (
-            @Schema(description = "페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.")
+    @Operation(summary = "공연목록",
+            description = """
+                    <h3>공연 전체 목록을 조회하는 통합 API입니다.</h3>
+                    <hr/>
+                    다양한 조회 기준에 따라 공연 목록을 조회합니다.<br/>
+                    """)
+    @GetMapping("list/{sort}")
+    public RsData<List<ConcertItem>> getList(
+            @Schema(description = """
+                    <h3>리스트를 받아올 기준이 될 경로 변수입니다. <b>대문자</b>로 예시에 있는 것만 사용해 주세요.</h3>
+                    <hr/>
+                    <b>LIKE :</b> 좋아요 순<br/>
+                    <b>VIEW :</b> 조회수 순<br/>
+                    <b>TICKETING :</b> 오늘을 기준으로 다가오는 티켓팅 날짜 순<br/>
+                    <b>UPCOMING :</b> 오늘을 기준으로 다가오는 공연 시작 날짜 순<br/>
+                    <b>REGISTERED :</b> 가장 최근에 API에 등록된 공연 순<br/>
+                    <hr/>
+                    """, examples = {"LIKE", "VIEW", "TICKETING", "UPCOMING", "REGISTERED"})
+            @PathVariable ListSort sort,
+            @Schema(description = """
+                    페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.<br/>
+                    sort 부분은 사용하지 않으니 지워주시고 <strong>"page", "size"</strong> 만 넘겨주시면 됩니다. <font color="red">*sort 부분이 남아있으면 오류가 발생합니다.</font>
+                    """)
             Pageable pageable
     ) {
-      return RsData.success(concertService.getUpcomingConcertsList(pageable));
-    }
-
-    // todo: 내용 구현 필요
-    @Operation(summary = "공연 예매일 기준 조회(구현 전)", description = "현 시간을 기준으로 예매시간을 내림차순으로 출력하는 공연 목록을 조회합니다.")
-    @GetMapping("upComingTicketingList")
-    public RsData<List<ConcertItem>> getUpComingTicketingList (
-            @Schema(description = "페이징 처리 또는 무한 스크롤 구현에 사용할 Pageable 객체입니다.")
-            Pageable pageable
-    ){
-        return null;
+        return RsData.success(concertService.getConcertsList(pageable, sort));
     }
 
     @Operation(summary = "좋아요 한 공연 조회", description = "좋아요를 누른 공연에 대한 목록을 조회합니다. 저장 날짜를 기준으로 내림차순 정렬로 표시합니다.(최신으로 추가된 목록순입니다.)")
     @GetMapping("likedConcertList")
-    public RsData<List<ConcertItem>> getLikedConcertList (
+    public RsData<List<ConcertItem>> getLikedConcertList(
             @Schema(description = "페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.")
             Pageable pageable
-    ){
+    ) {
         User user = rq.getUser();
-        return RsData.success(concertService.getLikedConcertsList(pageable,user));
+        return RsData.success(concertService.getLikedConcertsList(pageable, user));
     }
 
     @Operation(summary = "공연 상세 조회", description = "공연에 대한 상세 목록을 조회합니다.")
     @GetMapping("concertDetail")
     public ConcertDetailResponse getConcertDetail(
             @RequestParam
-            @Schema(description = "조회 기준이 되는 concertId입니다. ?concertId={concertId} 로 값을 넘기시면 됩니다.")
+            @Schema(description = """
+                    <h3>조회 기준이 되는 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값을 기준으로 조회합니다. <br/>
+                    <strong>?concertId={concertId}</strong> 로 값을 넘기시면 됩니다.
+                    """)
             long concertId
     ) {
         return concertService.getConcertDetail(concertId);
     }
 
     @Operation(summary = "공연 예매처 조회", description = "공연에 대한 예매처들을 조회합니다.")
     @GetMapping("ticketOffices")
-    public RsData<List<TicketOfficeElement>> getTicketOffices (
+    public RsData<List<TicketOfficeElement>> getTicketOffices(
             @RequestParam
-            @Schema(description = "조회 기준이 되는 concertId입니다. ?concertId={concertId} 로 값을 넘기시면 됩니다.")
+            @Schema(description = """
+                    <h3>조회 기준이 되는 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값을 기준으로 조회합니다. <br/>
+                    <strong>?concertId={concertId}</strong> 로 값을 넘기시면 됩니다.
+                    """)
             long concertId
-    ){
+    ) {
         return RsData.success(concertService.getTicketOfficesList(concertId));
     }
 
     @Operation(summary = "공연 좋아요 기능", description = "사용자가 마음에 드는 공연에 대해 좋아요를 통해 저장할 수 있습니다.")
     @PostMapping("like/{concertId}")
     public RsData<Void> likeConcert(
-            @PathVariable long concertId
+            @PathVariable
+            @Schema(description = """
+                    <h3>좋아요를 누를 공연의 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값입니다. <br/>
+                    <strong>/like/{concertId}</strong> 형태로 요청하면 해당 공연에 좋아요가 등록됩니다.
+                    """)
+            long concertId
     ) {
         User user = rq.getUser();
         concertService.likeConcert(concertId, user);
@@ -108,7 +126,14 @@ public RsData<Void> likeConcert(
     @Operation(summary = "공연 좋아요 해제 기능", description = "좋아요를 해제할 수 있습니다.")
     @DeleteMapping("dislike/{concertId}")
     public RsData<Void> dislikeConcert(
-            @PathVariable long concertId
+            @PathVariable
+            @Schema(description = """
+                    <h3>좋아요를 해제할 공연의 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값입니다. <br/>
+                    <strong>/dislike/{concertId}</strong> 형태로 요청하면 좋아요가 해제됩니다.
+                    """)
+            long concertId
     ) {
         User user = rq.getUser();
         concertService.dislikeConcert(concertId, user);
@@ -118,8 +143,15 @@ public RsData<Void> dislikeConcert(
     @Operation(summary = "공연 좋아요 여부 확인", description = "좋아요 여부를 확인합니다.")
     @GetMapping("isLike/{concertId}")
     public RsData<ConcertLikeResponse> isLikeConcert(
-            @PathVariable long concertId
-    ){
+            @PathVariable
+            @Schema(description = """
+                    <h3>좋아요 여부를 확인할 공연의 concertId입니다.</h3>
+                    <hr/>
+                    DB에 저장되어 있는 공연의 ID 값입니다. <br/>
+                    <strong>/isLike/{concertId}</strong> 형태로 요청하면 좋아요 여부를 확인할 수 있습니다.
+                    """)
+            long concertId
+    ) {
         User user = rq.getUser();
         return RsData.success(concertService.isLikeConcert(concertId, user));
     }
@@ -128,13 +160,18 @@ public RsData<ConcertLikeResponse> isLikeConcert(
     @Operation(summary = "공연 검색", description = "제목에 키워드를 포함하고 있는 공연 정보를 검색합니다.")
     @GetMapping("search")
     public RsData<List<ConcertItem>> searchConcert(
-            @Schema(description = "공연 정보 검색 키워드입니다.")
+            @Schema(description = """
+                    <h3>검색어가 되는 Keyword입니다.</h3>
+                    <hr/>
+                    <b>?keyword={keyword}</b> 로 값을 넘기시면 됩니다.<br/>
+                    DB에서 해당 문자열을 가지고 있는 모든 결과값을 반환합니다.
+                    """)
             @RequestParam String keyword,
             @Schema(description = "페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.")
             Pageable pageable
 
-    ){
-        return RsData.success(concertService.getConcertListByKeyword(keyword,pageable));
+    ) {
+        return RsData.success(concertService.getConcertListByKeyword(keyword, pageable));
     }
 
 }

src/main/java/com/back/web7_9_codecrete_be/domain/concerts/dto/concert/ConcertLikeResponse.java

@@ -1,7 +1,6 @@
 package com.back.web7_9_codecrete_be.domain.concerts.dto.concert;
 
 import com.back.web7_9_codecrete_be.domain.concerts.entity.Concert;
-import com.back.web7_9_codecrete_be.domain.concerts.entity.ConcertLike;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 

src/main/java/com/back/web7_9_codecrete_be/domain/concerts/dto/concert/ConcertTicketTimeSetRequest.java

@@ -1,15 +1,18 @@
 package com.back.web7_9_codecrete_be.domain.concerts.dto.concert;
 
 import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotEmpty;
 import lombok.Getter;
 
 import java.time.LocalDateTime;
 
 @Getter
 public class ConcertTicketTimeSetRequest {
     @Schema(description = "공연 ID 입니다.")
+    @NotEmpty
     private Long  concertId;
 
     @Schema(description = "티켓팅 시간입니다.")
+    @NotEmpty
     private LocalDateTime ticketTime;
 }

src/main/java/com/back/web7_9_codecrete_be/domain/concerts/dto/concert/ConcertUpdateRequest.java

@@ -1,36 +1,46 @@
 package com.back.web7_9_codecrete_be.domain.concerts.dto.concert;
 
 import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotEmpty;
 import lombok.Getter;
 
 import java.time.LocalDate;
 
 @Getter
 public class ConcertUpdateRequest {
     @Schema(description = "수정할 대상이 될 공연 ID 입니다.")
+    @NotEmpty
     private Long concertId;
 
     @Schema(description = "공연 이름입니다.")
+    @NotEmpty
     private String name;
 
     @Schema(description = "공연 설명입니다.")
+    @NotEmpty
     private String description;
 
     @Schema(description = "공연장 ID 입니다.")
+    @NotEmpty
     private Long placeId;
 
     @Schema(description = "공연 시작 날짜입니다.")
+    @NotEmpty
     private LocalDate StartDate;
 
     @Schema(description = "공연 종료 날짜입니다.")
+    @NotEmpty
     private LocalDate EndDate;
 
     @Schema(description = "공연 포스터 URL 입니다.")
+    @NotEmpty
     private String posterUrl;
 
     @Schema(description = "공연 티켓 최고가입니다.")
+    @NotEmpty
     private int maxPrice;
 
     @Schema(description = "공연 티켓 최저가입니다.")
+    @NotEmpty
     private int minPrice;
 }

src/main/java/com/back/web7_9_codecrete_be/domain/concerts/dto/concert/ListSort.java

@@ -0,0 +1,9 @@
+package com.back.web7_9_codecrete_be.domain.concerts.dto.concert;
+
+public enum ListSort {
+    LIKE,
+    VIEW,
+    TICKETING,
+    UPCOMING,
+    REGISTERED;
+}