Skip to content

Commit 89c0df0

Browse files
CreamcheesepieCreamcheesepie
committed
feat : 스웨거 설명 보강
1 parent d74babf commit 89c0df0

2 files changed

Lines changed: 101 additions & 30 deletions

File tree

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

Lines changed: 49 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -35,16 +35,27 @@ public RsData<SetResultResponse> setConcert() throws InterruptedException {
3535
return RsData.success(kopisApiService.setConcertsList());
3636
}
3737

38-
@Operation(summary = "공연 정보 갱신",description = "공연 정보를 직접 갱신합니다.")
38+
@Operation(summary = "공연 정보 갱신", description = "공연 정보를 직접 갱신합니다.")
3939
@PatchMapping("updateConcert/{concertId}")
4040
public RsData<ConcertItem> updateConcert(
41-
@Schema(description = "갱신 대상이 될 공연의 ID 값입니다.")
42-
@PathVariable Long concertId,
43-
@Schema(description = "갱신 내용입니다.")
44-
@RequestBody ConcertUpdateRequest concertUpdateRequest
45-
){
41+
@PathVariable
42+
@Schema(description = """
43+
<h3>갱신 대상이 될 공연의 concertId입니다.</h3>
44+
<hr/>
45+
DB에 저장되어 있는 공연의 ID 값입니다. <br/>
46+
<strong>/updateConcert/{concertId}</strong> 형태로 요청하면 됩니다.
47+
""")
48+
Long concertId,
49+
@RequestBody
50+
@Schema(description = """
51+
<h3>공연 갱신 요청 정보입니다.</h3>
52+
<hr/>
53+
공연의 제목, 설명 등 수정이 필요한 정보들을 전달합니다.
54+
""")
55+
ConcertUpdateRequest concertUpdateRequest
56+
) {
4657
ConcertItem concertItem = concertService.updateConcert(concertId, concertUpdateRequest);
47-
return RsData.success("공연 정보 수정이 완료되었습니다.",concertItem);
58+
return RsData.success("공연 정보 수정이 완료되었습니다.", concertItem);
4859
}
4960

5061
@Operation(summary = "예매 시간이 없는 공연 목록 조회", description = "예매 시간이 없는 공연들을 공연시간 내림차순으로 출력합니다.")
@@ -58,25 +69,46 @@ public List<ConcertItem> getNoTicketTimeConcertsList(
5869

5970
@Operation(summary = "공연을 삭제합니다.", description = "해당 공연을 삭제합니다.")
6071
@DeleteMapping("deleteConcert/{concertId}")
61-
public RsData<Void> deleteConcert(@PathVariable Long concertId){
72+
public RsData<Void> deleteConcert(
73+
@PathVariable
74+
@Schema(description = """
75+
<h3>삭제 대상이 될 공연의 concertId입니다.</h3>
76+
<hr/>
77+
DB에 저장되어 있는 공연의 ID 값입니다. <br/>
78+
<strong>/deleteConcert/{concertId}</strong> 형태로 요청하면 됩니다.
79+
""")
80+
Long concertId
81+
) {
6282
concertService.deleteConcert(concertId);
63-
return RsData.success("공연 정보 삭제에 성공하였습니다.",null);
83+
return RsData.success("공연 정보 삭제에 성공하였습니다.", null);
6484
}
6585

66-
@Operation(summary = "예매 시간 등록",description = "개별 공연에 대한 예매 시간을 설정합니다.")
86+
@Operation(summary = "예매 시간 등록", description = "개별 공연에 대한 예매 시간을 설정합니다.")
6787
@PatchMapping("ticketTimeSet")
68-
public RsData<ConcertDetailResponse> ticketTimeSet(
69-
@RequestBody ConcertTicketTimeSetRequest concertTicketTimeSetRequest
70-
){
88+
public RsData<ConcertDetailResponse> ticketTimeSet(
89+
@RequestBody
90+
@Schema(description = """
91+
<h3>공연 예매 시간 설정 정보입니다.</h3>
92+
<hr/>
93+
공연 ID와 예매 시작 시간 정보를 전달합니다.
94+
""")
95+
ConcertTicketTimeSetRequest concertTicketTimeSetRequest
96+
) {
7197
return RsData.success(concertService.setConcertTime(concertTicketTimeSetRequest));
7298
}
7399

74-
@Operation(summary = "개별 공연 API통한 갱신",description = "개별 공연에 대해서 공연 예술 통합망(Kopis)을 통해 데이터를 조회하고 해당 데이터를 갱신합니다.")
100+
@Operation(summary = "개별 공연 API통한 갱신", description = "개별 공연에 대해서 공연 예술 통합망(Kopis)을 통해 데이터를 조회하고 해당 데이터를 갱신합니다.")
75101
@PatchMapping("updateConcertByKopisAPI/{concertId}")
76102
public RsData<ConcertDetailResponse> updateConcertByKopisAPI(
77-
@Schema(description = "갱신 대상이 될 공연의 ID 값입니다.")
78-
@PathVariable Long concertId
79-
){
103+
@PathVariable
104+
@Schema(description = """
105+
<h3>갱신 대상이 될 공연의 concertId입니다.</h3>
106+
<hr/>
107+
DB에 저장되어 있는 공연의 ID 값입니다. <br/>
108+
<strong>/updateConcertByKopisAPI/{concertId}</strong> 형태로 요청하면 됩니다.
109+
""")
110+
Long concertId
111+
) {
80112
kopisApiService.concertUpdateByKopisApi(concertId);
81113
return RsData.success(concertService.getConcertDetail(concertId));
82114
}

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

Lines changed: 52 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -47,17 +47,20 @@ public class ConcertController {
4747
@GetMapping("list/{sort}")
4848
public RsData<List<ConcertItem>> getList(
4949
@Schema(description = """
50-
<h3>리스트를 받아올 기준이 될 경로 변수입니다. 대문자로 예시에 있는 것만 사용해 주세요.</h3>
50+
<h3>리스트를 받아올 기준이 될 경로 변수입니다. <b>대문자</b>로 예시에 있는 것만 사용해 주세요.</h3>
5151
<hr/>
52-
LIKE : 좋아요 순<br/>
53-
VIEW : 조회수 순<br/>
54-
TICKETING : 오늘을 기준으로 다가오는 티켓팅 날짜 순<br/>
55-
UPCOMING : 오늘을 기준으로 다가오는 공연 시작 날짜 순<br/>
56-
REGISTERED : 가장 최근에 API에 등록된 공연 순<br/>
52+
<b>LIKE :</b> 좋아요 순<br/>
53+
<b>VIEW :</b> 조회수 순<br/>
54+
<b>TICKETING :</b> 오늘을 기준으로 다가오는 티켓팅 날짜 순<br/>
55+
<b>UPCOMING :</b> 오늘을 기준으로 다가오는 공연 시작 날짜 순<br/>
56+
<b>REGISTERED :</b> 가장 최근에 API에 등록된 공연 순<br/>
5757
<hr/>
5858
""", examples = {"LIKE", "VIEW", "TICKETING", "UPCOMING", "REGISTERED"})
5959
@PathVariable ListSort sort,
60-
@Schema(description = "페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.")
60+
@Schema(description = """
61+
페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.<br/>
62+
sort 부분은 사용하지 않으니 지워주시고 <strong>"page", "size"</strong> 만 넘겨주시면 됩니다. <font color="red">*sort 부분이 남아있으면 오류가 발생합니다.</font>
63+
""")
6164
Pageable pageable
6265
) {
6366
return RsData.success(concertService.getConcertsList(pageable, sort));
@@ -77,7 +80,12 @@ public RsData<List<ConcertItem>> getLikedConcertList(
7780
@GetMapping("concertDetail")
7881
public ConcertDetailResponse getConcertDetail(
7982
@RequestParam
80-
@Schema(description = "조회 기준이 되는 concertId입니다. ?concertId={concertId} 로 값을 넘기시면 됩니다.")
83+
@Schema(description = """
84+
<h3>조회 기준이 되는 concertId입니다.</h3>
85+
<hr/>
86+
DB에 저장되어 있는 공연의 ID 값을 기준으로 조회합니다. <br/>
87+
<strong>?concertId={concertId}</strong> 로 값을 넘기시면 됩니다.
88+
""")
8189
long concertId
8290
) {
8391
return concertService.getConcertDetail(concertId);
@@ -87,7 +95,12 @@ public ConcertDetailResponse getConcertDetail(
8795
@GetMapping("ticketOffices")
8896
public RsData<List<TicketOfficeElement>> getTicketOffices(
8997
@RequestParam
90-
@Schema(description = "조회 기준이 되는 concertId입니다. ?concertId={concertId} 로 값을 넘기시면 됩니다.")
98+
@Schema(description = """
99+
<h3>조회 기준이 되는 concertId입니다.</h3>
100+
<hr/>
101+
DB에 저장되어 있는 공연의 ID 값을 기준으로 조회합니다. <br/>
102+
<strong>?concertId={concertId}</strong> 로 값을 넘기시면 됩니다.
103+
""")
91104
long concertId
92105
) {
93106
return RsData.success(concertService.getTicketOfficesList(concertId));
@@ -96,7 +109,14 @@ public RsData<List<TicketOfficeElement>> getTicketOffices(
96109
@Operation(summary = "공연 좋아요 기능", description = "사용자가 마음에 드는 공연에 대해 좋아요를 통해 저장할 수 있습니다.")
97110
@PostMapping("like/{concertId}")
98111
public RsData<Void> likeConcert(
99-
@PathVariable long concertId
112+
@PathVariable
113+
@Schema(description = """
114+
<h3>좋아요를 누를 공연의 concertId입니다.</h3>
115+
<hr/>
116+
DB에 저장되어 있는 공연의 ID 값입니다. <br/>
117+
<strong>/like/{concertId}</strong> 형태로 요청하면 해당 공연에 좋아요가 등록됩니다.
118+
""")
119+
long concertId
100120
) {
101121
User user = rq.getUser();
102122
concertService.likeConcert(concertId, user);
@@ -106,7 +126,14 @@ public RsData<Void> likeConcert(
106126
@Operation(summary = "공연 좋아요 해제 기능", description = "좋아요를 해제할 수 있습니다.")
107127
@DeleteMapping("dislike/{concertId}")
108128
public RsData<Void> dislikeConcert(
109-
@PathVariable long concertId
129+
@PathVariable
130+
@Schema(description = """
131+
<h3>좋아요를 해제할 공연의 concertId입니다.</h3>
132+
<hr/>
133+
DB에 저장되어 있는 공연의 ID 값입니다. <br/>
134+
<strong>/dislike/{concertId}</strong> 형태로 요청하면 좋아요가 해제됩니다.
135+
""")
136+
long concertId
110137
) {
111138
User user = rq.getUser();
112139
concertService.dislikeConcert(concertId, user);
@@ -116,7 +143,14 @@ public RsData<Void> dislikeConcert(
116143
@Operation(summary = "공연 좋아요 여부 확인", description = "좋아요 여부를 확인합니다.")
117144
@GetMapping("isLike/{concertId}")
118145
public RsData<ConcertLikeResponse> isLikeConcert(
119-
@PathVariable long concertId
146+
@PathVariable
147+
@Schema(description = """
148+
<h3>좋아요 여부를 확인할 공연의 concertId입니다.</h3>
149+
<hr/>
150+
DB에 저장되어 있는 공연의 ID 값입니다. <br/>
151+
<strong>/isLike/{concertId}</strong> 형태로 요청하면 좋아요 여부를 확인할 수 있습니다.
152+
""")
153+
long concertId
120154
) {
121155
User user = rq.getUser();
122156
return RsData.success(concertService.isLikeConcert(concertId, user));
@@ -126,7 +160,12 @@ public RsData<ConcertLikeResponse> isLikeConcert(
126160
@Operation(summary = "공연 검색", description = "제목에 키워드를 포함하고 있는 공연 정보를 검색합니다.")
127161
@GetMapping("search")
128162
public RsData<List<ConcertItem>> searchConcert(
129-
@Schema(description = "공연 정보 검색 키워드입니다.")
163+
@Schema(description = """
164+
<h3>검색어가 되는 Keyword입니다.</h3>
165+
<hr/>
166+
<b>?keyword={keyword}</b> 로 값을 넘기시면 됩니다.<br/>
167+
DB에서 해당 문자열을 가지고 있는 모든 결과값을 반환합니다.
168+
""")
130169
@RequestParam String keyword,
131170
@Schema(description = "페이징 처리 또는 무한 스크롤 구현에 쓸 Pageable 객체입니다.")
132171
Pageable pageable

0 commit comments

Comments
 (0)