Skip to content

Commit e7aadde

Browse files
ohofrontohofront
authored
Merge pull request #51 from JocketDan/docs/swagger-tour-open-api-docs
Docs : add Swagger annotations and description
2 parents 586f34b + a165c96 commit e7aadde

1 file changed

Lines changed: 147 additions & 7 deletions

File tree

‎tour/src/main/java/com/jocketdan/tour/controller/TourOpenApiController.java‎

Lines changed: 147 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
import com.jocketdan.tour.dto.openApi.*;
44
import com.jocketdan.tour.service.TourOpenApiService;
5+
import io.swagger.v3.oas.annotations.Operation;
6+
import io.swagger.v3.oas.annotations.Parameter;
57
import lombok.AccessLevel;
68
import lombok.RequiredArgsConstructor;
79
import lombok.experimental.FieldDefaults;
@@ -16,60 +18,198 @@ public class TourOpenApiController {
1618

1719
TourOpenApiService tourOpenApiService;
1820

21+
@Operation(
22+
summary = "지역 기반 관광정보 조회",
23+
description = """
24+
지역(법정동/시군구 코드)을 기반으로 관광 정보를 조회합니다.
25+
<br/><br/>
26+
**정렬 구분 (arrange)**
27+
- A: 제목순
28+
- C: 수정일순
29+
- D: 생성일순
30+
- O: 대표이미지 있는 제목순
31+
- Q: 대표이미지 있는 수정일순
32+
- R: 대표이미지 있는 생성일순
33+
<br/><br/>
34+
**관광 타입 (contentTypeId)**
35+
- 12: 관광지
36+
- 14: 문화시설
37+
- 15: 축제/공연/행사
38+
- 25: 여행코스
39+
- 28: 레포츠
40+
- 32: 숙박
41+
- 38: 쇼핑
42+
- 39: 음식점
43+
"""
44+
)
1945
@GetMapping("/api/tour/areaBasedList")
2046
public AreaBasedListResponseDTO getAreaBasedList(
2147
@RequestParam(defaultValue = "10") int numOfRows,
2248
@RequestParam(defaultValue = "1") int pageNo,
49+
50+
@Parameter(description = "정렬 구분 (A, C, D, O, Q, R)", example = "A")
2351
@RequestParam(defaultValue = "A") String arrange,
52+
53+
@Parameter(description = "관광 타입 ID", example = "12")
2454
@RequestParam(required = false) String contentTypeId,
55+
56+
@Parameter(description = "법정동 코드")
2557
@RequestParam(required = false) String lDongRegnCd,
58+
59+
@Parameter(description = "시군구 코드")
2660
@RequestParam(required = false) String lDongSignguCd
2761
) {
2862
return tourOpenApiService.getAreaBasedList(numOfRows, pageNo, arrange, contentTypeId, lDongRegnCd, lDongSignguCd);
2963
}
3064

65+
66+
@Operation(
67+
summary = "축제(Festival) 정보 조회",
68+
description = """
69+
현재 또는 특정 기간의 축제/행사 정보를 조회합니다.
70+
<br/><br/>
71+
**정렬 구분 (arrange)**
72+
- A: 제목순
73+
- C: 수정일순
74+
- D: 생성일순
75+
- O: 대표이미지 있는 제목순
76+
- Q: 대표이미지 있는 수정일순
77+
- R: 대표이미지 있는 생성일순
78+
"""
79+
)
3180
@GetMapping("/api/tour/searchFestival")
3281
public SearchFestivalResponseDTO getSearchFestival(
3382
@RequestParam(defaultValue = "10") int numOfRows,
3483
@RequestParam(defaultValue = "1") int pageNo,
84+
85+
@Parameter(description = "정렬 구분 (A, C, D, O, Q, R)", example = "A")
3586
@RequestParam(defaultValue = "A") String arrange,
36-
@RequestParam(required = false) String lDongRegnCd,
37-
@RequestParam(required = false) String lDongSignguCd,
87+
88+
@Parameter(description = "법정동 코드") @RequestParam(required = false)
89+
String lDongRegnCd,
90+
91+
@Parameter(description = "시군구 코드") @RequestParam(required = false)
92+
String lDongSignguCd,
93+
94+
@Parameter(description = "행사 시작일 (YYYYMMDD)", example = "20251001")
3895
@RequestParam String eventStartDate
3996
) {
4097
return tourOpenApiService.getSearchFestival(numOfRows, pageNo, arrange, lDongRegnCd, lDongSignguCd, eventStartDate);
4198
}
4299

100+
@Operation(
101+
summary = "키워드 기반 관광정보 조회",
102+
description = """
103+
키워드를 기반으로 관광지를 검색합니다.
104+
<br/><br/>
105+
**정렬 구분 (arrange)**
106+
- A: 제목순
107+
- C: 수정일순
108+
- D: 생성일순
109+
- O: 대표이미지 있는 제목순
110+
- Q: 대표이미지 있는 수정일순
111+
- R: 대표이미지 있는 생성일순
112+
<br/><br/>
113+
**관광 타입 (contentTypeId)**
114+
- 12: 관광지
115+
- 14: 문화시설
116+
- 15: 축제/공연/행사
117+
- 25: 여행코스
118+
- 28: 레포츠
119+
- 32: 숙박
120+
- 38: 쇼핑
121+
- 39: 음식점
122+
"""
123+
)
43124
@GetMapping("/api/tour/searchKeyword")
44125
public SearchKeywordResponseDTO getSearchKeyword(
45126
@RequestParam(defaultValue = "10") int numOfRows,
46127
@RequestParam(defaultValue = "1") int pageNo,
128+
@Parameter(description = "정렬 구분 (A, C, D, O, Q, R)", example = "A")
47129
@RequestParam(defaultValue = "A") String arrange,
130+
131+
@Parameter(description = "관광 타입 ID", example = "12")
48132
@RequestParam(required = false) String contentTypeId,
49-
@RequestParam(required = false) String lDongRegnCd,
50-
@RequestParam(required = false) String lDongSignguCd,
133+
134+
@Parameter(description = "법정동 코드") @RequestParam(required = false)
135+
String lDongRegnCd,
136+
137+
@Parameter(description = "시군구 코드") @RequestParam(required = false)
138+
String lDongSignguCd,
139+
140+
@Parameter(description = "검색 키워드", example = "서울")
51141
@RequestParam String keyword
52142
) {
53143
return tourOpenApiService.getSearchKeyword(numOfRows, pageNo, arrange, contentTypeId, lDongRegnCd, lDongSignguCd, keyword);
54144
}
55145

146+
@Operation(
147+
summary = "위치 기반 관광정보 조회",
148+
description = """
149+
사용자의 위치(GPS 좌표)를 기반으로 반경 내 관광 정보를 조회합니다.
150+
<br/><br/>
151+
**정렬 구분 (arrange)**
152+
- A: 제목순
153+
- C: 수정일순
154+
- D: 생성일순
155+
- E: 거리순
156+
- O: 대표이미지 있는 제목순
157+
- Q: 대표이미지 있는 수정일순
158+
- R: 대표이미지 있는 생성일순
159+
- S: 대표이미지 있는 거리순
160+
<br/><br/>
161+
**관광 타입 (contentTypeId)**
162+
- 12: 관광지
163+
- 14: 문화시설
164+
- 15: 축제/공연/행사
165+
- 25: 여행코스
166+
- 28: 레포츠
167+
- 32: 숙박
168+
- 38: 쇼핑
169+
- 39: 음식점
170+
<br/><br/>
171+
**좌표 정보**
172+
- mapX: GPS X좌표 (WGS84 경도)
173+
- mapY: GPS Y좌표 (WGS84 위도)
174+
- radius: 검색 반경 (m), 최대 20000m (20km)
175+
"""
176+
)
56177
@GetMapping("/api/tour/locationBasedList")
57178
public LocationBasedListResponseDTO getLocationBasedList(
58179
@RequestParam(defaultValue = "10") int numOfRows,
59180
@RequestParam(defaultValue = "1") int pageNo,
181+
@Parameter(description = "정렬 구분 (A, C, D, E, O, Q, R, S)", example = "E")
60182
@RequestParam(defaultValue = "A") String arrange,
183+
184+
@Parameter(description = "관광 타입 ID", example = "12")
61185
@RequestParam(required = false) String contentTypeId,
62-
@RequestParam(required = false) String lDongRegnCd,
63-
@RequestParam(required = false) String lDongSignguCd,
186+
187+
@Parameter(description = "법정동 코드") @RequestParam(required = false)
188+
String lDongRegnCd,
189+
190+
@Parameter(description = "시군구 코드") @RequestParam(required = false)
191+
String lDongSignguCd,
192+
193+
@Parameter(description = "GPS X좌표 (경도)", example = "126.9784")
64194
@RequestParam String mapX,
195+
196+
@Parameter(description = "GPS Y좌표 (위도)", example = "37.5667")
65197
@RequestParam String mapY,
198+
199+
@Parameter(description = "검색 반경 (단위: m, 최대 20000)", example = "5000")
66200
@RequestParam String radius
67201
) {
68202
return tourOpenApiService.getLocationBasedList(numOfRows, pageNo, arrange, contentTypeId, lDongRegnCd, lDongSignguCd, mapX, mapY, radius);
69203
}
70204

205+
@Operation(
206+
summary = "관광지 상세정보 조회",
207+
description = "contentId를 이용해 관광지의 상세 정보를 조회합니다."
208+
)
71209
@GetMapping("/api/tour/details")
72-
public DetailsResponseDTO getDetails(String contentId) {
210+
public DetailsResponseDTO getDetails(
211+
@Parameter(description = "관광 콘텐츠 ID", example = "1234567") @RequestParam String contentId
212+
) {
73213
return tourOpenApiService.getDetails(contentId);
74214
}
75215
}

0 commit comments

Comments
 (0)