Merge pull request #83 from prgrms-web-devcourse-final-project/feat/#81

[Concert] 공연관련 Swagger 문서화

Author: Creamcheesepie

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

@@ -9,6 +9,8 @@
 import com.back.web7_9_codecrete_be.domain.concerts.service.ConcertService;
 import com.back.web7_9_codecrete_be.domain.concerts.service.KopisApiService;
 import com.back.web7_9_codecrete_be.global.rsData.RsData;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.domain.Pageable;
@@ -25,43 +27,63 @@ public class ConcertAdminController { // todo : 인증 권한 추가하기
     private final ConcertService concertService;
     private final KopisApiService kopisApiService;
 
-    @GetMapping("totalGetTest")
-    public ConcertListResponse totalGetTest() throws InterruptedException {
-        return kopisApiService.setConcertsList();
-    }
-
 
-    @GetMapping("setConcertPlace")
+    @Operation(summary = "초기 공연 정보 저장", description = "25년 12월부터 앞으로 6개월 이후까지의 전체 공연의 정보를 가져와서 저장합니다. 대략 10~12분 정도 시간이 소요됩니다.")
+    @PostMapping("setConcertPlace")
     public ConcertPlaceListResponse setConcertPlace() throws InterruptedException {
         return kopisApiService.setConcertPlace();
     }
 
+    @Operation(summary = "공연 정보 갱신",description = "공연 정보를 직접 갱신합니다.")
     @PatchMapping("updateConcert/{concertId}")
     public RsData<ConcertItem> updateConcert(
+            @Schema(description = "갱신 대상이 될 공연의 ID 값입니다.")
             @PathVariable Long concertId,
+            @Schema(description = "갱신 내용입니다.")
             @RequestBody ConcertUpdateRequest concertUpdateRequest
     ){
         ConcertItem concertItem = concertService.updateConcert(concertId, concertUpdateRequest);
         return RsData.success("공연 정보 수정이 완료되었습니다.",concertItem);
     }
 
+    @Operation(summary = "예매 시간이 없는 공연 목록 조회", description = "예매 시간이 없는 공연들을 공연시간 내림차순으로 출력합니다.")
     @GetMapping("noTicketTimeList")
     public List<ConcertItem> getNoTicketTimeConcertsList(
+            @Schema(description = "무한스크롤 및 페이징 처리에 사용할 Pageable입니다.")
             Pageable pageable
     ) {
         return concertService.getNoTicketTimeConcertsList(pageable);
     }
 
+    @Operation(summary = "공연을 삭제합니다.", description = "해당 공연을 삭제합니다.")
     @DeleteMapping("deleteConcert/{concertId}")
     public RsData<Void> deleteConcert(@PathVariable Long concertId){
         concertService.deleteConcert(concertId);
         return RsData.success("공연 정보 삭제에 성공하였습니다.",null);
     }
 
+    @Operation(summary = "예매 시간 등록",description = "개별 공연에 대한 예매 시간을 설정합니다.")
     @PatchMapping("ticketTimeSet")
     public RsData<ConcertDetailResponse>  ticketTimeSet(
             @RequestBody ConcertTicketTimeSetRequest concertTicketTimeSetRequest
     ){
         return RsData.success(concertService.setConcertTime(concertTicketTimeSetRequest));
     }
+
+    // todo: 내용 구현 필요
+    @Operation(summary = "개별 공연 API통한 갱신(구현 전)",description = "개별 공연에 대해서 공연 예술 통합망(Kopis)을 통해 데이터를 조회하고 해당 데이터를 갱신합니다.")
+    @PatchMapping("updateConcertByKopisAPI/{concertId}")
+    public RsData<ConcertDetailResponse> updateConcertByKopisAPI(
+            @Schema(description = "갱신 대상이 될 공연의 ID 값입니다.")
+            @PathVariable Long ConcertId
+    ){
+        return null;
+    }
+
+    // todo: 내용 구현 필요, 결과 DTO 따로 만들기.
+    @Operation(summary = "공연 목록 갱신(구현 전)", description = "전체 공연에 대해서 공연 예술 통합망(Kopis)을 통해 데이터를 조회하고, 바뀐 내용을 갱신하고 추가된 공연을 가져옵니다.")
+    @PostMapping("updateConcert")
+    public RsData<Void> updateConcert(){
+        return null;
+    }
 }

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

@@ -24,6 +24,7 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.*;
 
+import javax.swing.*;
 import java.util.List;
 
 @RestController
@@ -52,6 +53,16 @@ public RsData<List<ConcertItem>> getUpComingList (
       return RsData.success(concertService.getUpcomingConcertsList(pageable));
     }
 
+    // todo: 내용 구현 필요
+    @Operation(summary = "공연 예매일 기준 조회(구현 전)", description = "현 시간을 기준으로 예매시간을 내림차순으로 출력하는 공연 목록을 조회합니다.")
+    @GetMapping("upComingTicketingList")
+    public RsData<List<ConcertItem>> getUpComingTicketingList (
+            @Schema(description = "페이징 처리 또는 무한 스크롤 구현에 사용할 Pageable 객체입니다.")
+            Pageable pageable
+    ){
+        return null;
+    }
+
     @Operation(summary = "좋아요 한 공연 조회", description = "좋아요를 누른 공연에 대한 목록을 조회합니다. 저장 날짜를 기준으로 내림차순 정렬로 표시합니다.(최신으로 추가된 목록순입니다.)")
     @GetMapping("likedConcertList")
     public RsData<List<ConcertItem>> getLikedConcertList (
@@ -72,8 +83,6 @@ public ConcertDetailResponse getConcertDetail(
         return concertService.getConcertDetail(concertId);
     }
 
-
-
     @Operation(summary = "공연 예매처 조회", description = "공연에 대한 예매처들을 조회합니다.")
     @GetMapping("ticketOffices")
     public RsData<List<TicketOfficeElement>> getTicketOffices (
@@ -113,5 +122,17 @@ public RsData<ConcertLikeResponse> isLikeConcert(
         return RsData.success(concertService.isLikeConcert(concertId, user));
     }
 
+    // todo : 내용 구현 필요
+    @Operation(summary = "공연 검색(구현 전)", description = "공연 정보를 검색합니다.")
+    @GetMapping("search")
+    public RsData<List<ConcertItem>> searchConcert(
+            @Schema(description = "공연 정보 검색 키워드입니다.")
+            @RequestParam String keyword
+    ){
+        return null;
+    }
+
+
+
 
 }

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

@@ -21,7 +21,7 @@ public class ConcertItem {
     @Schema(description = "콘서트 장소 이름입니다.")
     private String placeName;
 
-    @Schema(description = "콘서트 예매 시작 날짜입니다.")
+    @Schema(description = "콘서트 예매 시작 날짜입니다.",format = "yyyy-MM-ddThh:mm:ss")
     private LocalDateTime ticketTime;
 
     @Schema(description = "콘서트 시작 날짜입니다.",format = "yyyy-MM-dd")

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

@@ -2,11 +2,15 @@
 
 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;
 
 @Getter
 public class ConcertLikeResponse {
+    @Schema(description = "공연 ID 입니다.")
     private Long concertId;
+
+    @Schema(description = "공연 좋아요 여부입니다.")
     private Boolean isLike;
 
     public ConcertLikeResponse(Concert concert, Boolean isLike) {

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

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

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

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