Skip to content

Commit 4db0883

Browse files
tobbot16tobbot16
committed
feat: swagger ì작성 완료
1 parent b91dde2 commit 4db0883

11 files changed

Lines changed: 426 additions & 98 deletions

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/controller/KakaoApiController.java‎

Lines changed: 59 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
import com.back.web7_9_codecrete_be.global.rsData.RsData;
1717
import io.swagger.v3.oas.annotations.Operation;
1818
import io.swagger.v3.oas.annotations.Parameter;
19+
import io.swagger.v3.oas.annotations.media.ArraySchema;
20+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
1921
import io.swagger.v3.oas.annotations.tags.Tag;
2022
import io.swagger.v3.oas.annotations.media.Content;
2123
import io.swagger.v3.oas.annotations.media.Schema;
@@ -82,12 +84,29 @@ public RsData<String> coord2Address(
8284
return RsData.success("좌표를 주소로 변환했습니다.", addressName);
8385
}
8486

85-
87+
@Operation(
88+
summary = "자동차 길찾기 - 안내(Guide) 목록만 조회",
89+
description = "카카오 모빌리티 자동차 길찾기 결과에서 Guide(안내) 목록만 flatten 해서 반환합니다."
90+
)
91+
@ApiResponses({
92+
@ApiResponse(
93+
responseCode = "200",
94+
description = "조회 성공",
95+
content = @Content(array = @ArraySchema(schema = @Schema(implementation = KakaoMobilityResponse.Guide.class)))
96+
)
97+
})
8698
@GetMapping("/navigate/guides")
8799
public List<KakaoMobilityResponse.Guide> navigateGuides(
100+
@Parameter(description = "출발지 경도", example = "126.977969", required = true)
88101
@RequestParam double startX,
102+
103+
@Parameter(description = "출발지 위도", example = "37.566535", required = true)
89104
@RequestParam double startY,
105+
106+
@Parameter(description = "도착지 경도", example = "126.986037", required = true)
90107
@RequestParam double endX,
108+
109+
@Parameter(description = "도착지 위도", example = "37.563617", required = true)
91110
@RequestParam double endY
92111
) {
93112
KakaoMobilityResponse res = kakaoLocalService.NaviSearch(startX, startY, endX, endY);
@@ -107,12 +126,30 @@ public List<KakaoMobilityResponse.Guide> navigateGuides(
107126
.toList();
108127
}
109128

110-
129+
@Operation(
130+
summary = "자동차 길찾기 - 요약(Summary) 조회",
131+
description = "카카오 모빌리티 자동차 길찾기 결과에서 0번 route의 summary(총 거리/시간)를 반환합니다."
132+
)
133+
@ApiResponses({
134+
@ApiResponse(
135+
responseCode = "200",
136+
description = "조회 성공",
137+
content = @Content(schema = @Schema(implementation = KakaoMobilityResponse.Summary.class))
138+
),
139+
@ApiResponse(responseCode = "404", description = "경로를 찾을 수 없음", content = @Content)
140+
})
111141
@GetMapping("/navigate/summary")
112142
public KakaoMobilityResponse.Summary navigateSummary(
143+
@Parameter(description = "출발지 경도", example = "126.977969", required = true)
113144
@RequestParam double startX,
145+
146+
@Parameter(description = "출발지 위도", example = "37.566535", required = true)
114147
@RequestParam double startY,
148+
149+
@Parameter(description = "도착지 경도", example = "126.986037", required = true)
115150
@RequestParam double endX,
151+
152+
@Parameter(description = "도착지 위도", example = "37.563617", required = true)
116153
@RequestParam double endY
117154
) {
118155
KakaoMobilityResponse res = kakaoLocalService.NaviSearchSummary(startX, startY, endX, endY);
@@ -131,8 +168,27 @@ public KakaoMobilityResponse.Summary navigateSummary(
131168
}
132169

133170
//카카오 자동차 api인데, 경유지가 존재하는 경우에 사용
171+
@Operation(
172+
summary = "자동차 길찾기 - 경유지 포함(구간별) 요약 FE 응답",
173+
description = "경유지를 포함한 길찾기를 수행하고, 구간별(section) 거리/시간과 from→to 포인트를 FE용으로 재가공해 반환합니다."
174+
)
175+
@ApiResponses({
176+
@ApiResponse(
177+
responseCode = "200",
178+
description = "조회 성공",
179+
content = @Content(schema = @Schema(implementation = KakaoRouteSectionFeResponse.class))
180+
),
181+
@ApiResponse(responseCode = "400", description = "요청값 오류", content = @Content),
182+
@ApiResponse(responseCode = "404", description = "경로를 찾을 수 없음", content = @Content)
183+
})
134184
@PostMapping("/navigate/onlyguide")
135-
public KakaoRouteSectionFeResponse navigateOnlyGuides(@RequestBody KakaoRouteTransitRequest req
185+
public KakaoRouteSectionFeResponse navigateOnlyGuides(
186+
@io.swagger.v3.oas.annotations.parameters.RequestBody(
187+
description = "경유지 포함 길찾기 요청 바디",
188+
required = true,
189+
content = @Content(schema = @Schema(implementation = KakaoRouteTransitRequest.class))
190+
)
191+
@RequestBody KakaoRouteTransitRequest req
136192
) {
137193

138194
KakaoRouteTransitResponse res = kakaoLocalService.NaviSearchTransit(req);
@@ -178,38 +234,5 @@ public KakaoRouteSectionFeResponse navigateOnlyGuides(@RequestBody KakaoRouteTra
178234
sections
179235
);
180236
}
181-
182-
183-
// @GetMapping("/raw")
184-
// public KakaoMobilityResponse.Summary directionsRaw(
185-
// @RequestParam double startX,
186-
// @RequestParam double startY,
187-
// @RequestParam double endX,
188-
// @RequestParam double endY
189-
// ) {
190-
// PlanCostTimeResponse req = PlanCostTimeService.getCostTime(startX, startY, endX, endY);
191-
// return ResponseEntity.ok(raw);
192-
// }
193237
}
194238

195-
//@GetMapping("/navigate/summary")
196-
//public KakaoMobilityResponse.Summary navigateSummary(
197-
// @RequestParam double startX,
198-
// @RequestParam double startY,
199-
// @RequestParam double endX,
200-
// @RequestParam double endY
201-
//) {
202-
// KakaoMobilityResponse res = kakaoLocalService.NaviSearchSummary();
203-
//
204-
// if (res == null || res.getRoutes() == null || res.getRoutes().isEmpty()) {
205-
// throw new BusinessException(LocationErrorCode.ROUTE_NOT_FOUND);
206-
// }
207-
//
208-
// KakaoMobilityResponse.Route route0 = res.getRoutes().get(0);
209-
// if (route0.getSummary() == null) {
210-
// throw new BusinessException(LocationErrorCode.ROUTE_NOT_FOUND);
211-
// }
212-
//
213-
// return route0.getSummary();
214-
//
215-
//}

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/controller/PlanCostTimeController.java‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
import com.back.web7_9_codecrete_be.domain.location.dto.plan.PlanCostTimeRequest;
44
import com.back.web7_9_codecrete_be.domain.location.dto.plan.PlanCostTimeResponse;
55
import com.back.web7_9_codecrete_be.domain.location.service.PlanCostTimeService;
6+
import io.swagger.v3.oas.annotations.Operation;
7+
import io.swagger.v3.oas.annotations.media.Content;
8+
import io.swagger.v3.oas.annotations.media.Schema;
9+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
10+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
611
import lombok.RequiredArgsConstructor;
712
import org.springframework.web.bind.annotation.PostMapping;
813
import org.springframework.web.bind.annotation.RequestBody;
@@ -15,7 +20,32 @@
1520
public class PlanCostTimeController {
1621

1722
private final PlanCostTimeService planCostTimeService;
18-
23+
@Operation(
24+
summary = "이동 수단 기준 예상 비용/시간 계산",
25+
description = """
26+
출발지/도착지 좌표와 이동 수단(CAR, TRANSIT, WALK)을 기준으로
27+
예상 이동 비용과 소요 시간을 계산합니다.
28+
"""
29+
)
30+
@ApiResponses({
31+
@ApiResponse(
32+
responseCode = "200",
33+
description = "계산 성공",
34+
content = @Content(
35+
schema = @Schema(implementation = PlanCostTimeResponse.class)
36+
)
37+
),
38+
@ApiResponse(
39+
responseCode = "400",
40+
description = "잘못된 요청 값",
41+
content = @Content
42+
),
43+
@ApiResponse(
44+
responseCode = "404",
45+
description = "경로를 찾을 수 없음",
46+
content = @Content
47+
)
48+
})
1949
@PostMapping("/costtime")
2050
public PlanCostTimeResponse getCostTime(@RequestBody PlanCostTimeRequest request) {
2151
return planCostTimeService.getCostTime(request);

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/dto/fe/KakaoRouteFeResponse.java‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,26 @@
11
package com.back.web7_9_codecrete_be.domain.location.dto.fe;
22

3+
import io.swagger.v3.oas.annotations.media.Schema;
34
import lombok.AllArgsConstructor;
45
import lombok.Data;
56

67
@Data
78
@AllArgsConstructor
8-
public class KakaoRouteFeResponse { //경유지까지의 인덱스, 거리, 시간, 좌표를 나타냄
9+
@Schema(description = "프론트 전달용 구간 경로 정보 (경유지 인덱스/거리/시간/좌표)")
10+
public class KakaoRouteFeResponse {
11+
12+
@Schema(description = "구간 인덱스 (경유지 기준)", example = "0")
913
private int routeIndex;
14+
15+
@Schema(description = "구간 거리 (meter)", example = "1200")
1016
private int distance;
17+
18+
@Schema(description = "구간 소요 시간 (second)", example = "540")
1119
private int duration;
20+
21+
@Schema(description = "출발 좌표/지점 정보 (권장: DTO로 변경)", example = "{\"x\":126.977969,\"y\":37.566535}")
1222
private Object from;
13-
private Object to;
1423

24+
@Schema(description = "도착 좌표/지점 정보 (권장: DTO로 변경)", example = "{\"x\":126.986037,\"y\":37.563617}")
25+
private Object to;
1526
}

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/dto/fe/KakaoRouteSectionFeResponse.java‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,22 @@
11
package com.back.web7_9_codecrete_be.domain.location.dto.fe;
22

3+
import io.swagger.v3.oas.annotations.media.Schema;
34
import lombok.AllArgsConstructor;
45
import lombok.Data;
56

67
import java.util.List;
8+
79
@Data
810
@AllArgsConstructor
9-
public class KakaoRouteSectionFeResponse { //프론트에서 원하는 전체 거리, 시간, 좌표로, section에서는 경유지를 거치는 값들을 저장
11+
@Schema(description = "프론트 전달용 경로 정보 (총 거리/시간 + 구간 정보)")
12+
public class KakaoRouteSectionFeResponse {
13+
14+
@Schema(description = "전체 거리 (meter)", example = "8500")
1015
private int totalDistance;
16+
17+
@Schema(description = "전체 소요 시간 (second)", example = "3200")
1118
private int totalDuration;
19+
20+
@Schema(description = "구간(section) 목록")
1221
private List<KakaoRouteFeResponse> sections;
1322
}

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/dto/plan/PlanCostTimeRequest.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,31 @@
11
package com.back.web7_9_codecrete_be.domain.location.dto.plan;
22

33
import com.back.web7_9_codecrete_be.domain.plans.entity.Schedule;
4+
import io.swagger.v3.oas.annotations.media.Schema;
45
import lombok.AllArgsConstructor;
56
import lombok.Data;
67

78
@Data
89
@AllArgsConstructor
10+
@Schema(description = "이동 수단 기준 예상 비용/시간 계산 요청 DTO")
911
public class PlanCostTimeRequest {
1012

11-
// private Schedule.TransportType scheduleType;
13+
@Schema(description = "출발지 경도(longitude)", example = "126.977969", requiredMode = Schema.RequiredMode.REQUIRED)
1214
private double startX;
15+
16+
@Schema(description = "출발지 위도(latitude)", example = "37.566535", requiredMode = Schema.RequiredMode.REQUIRED)
1317
private double startY;
18+
19+
@Schema(description = "도착지 경도(longitude)", example = "126.986037", requiredMode = Schema.RequiredMode.REQUIRED)
1420
private double endX;
21+
22+
@Schema(description = "도착지 위도(latitude)", example = "37.563617", requiredMode = Schema.RequiredMode.REQUIRED)
1523
private double endY;
24+
25+
@Schema(
26+
description = "이동 수단 타입",
27+
example = "CAR",
28+
allowableValues = {"CAR", "TRANSIT", "WALK"}
29+
)
1630
private Schedule.TransportType transportType;
1731
}

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/dto/plan/PlanCostTimeResponse.java‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,19 @@
11
package com.back.web7_9_codecrete_be.domain.location.dto.plan;
22

3+
import io.swagger.v3.oas.annotations.media.Schema;
34
import lombok.AllArgsConstructor;
45
import lombok.Data;
56
import lombok.NoArgsConstructor;
67

78
@Data
89
@NoArgsConstructor
910
@AllArgsConstructor
11+
@Schema(description = "이동 수단 기준 예상 비용/시간 응답 DTO")
1012
public class PlanCostTimeResponse {
1113

14+
@Schema(description = "예상 비용 (원)", example = "12000")
1215
private Integer cost;
1316

17+
@Schema(description = "예상 소요 시간 (분)", example = "35")
1418
private Integer time;
15-
1619
}

‎src/main/java/com/back/web7_9_codecrete_be/domain/location/dto/request/kakao/KakaoRouteTransitRequest.java‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,67 @@
11
package com.back.web7_9_codecrete_be.domain.location.dto.request.kakao;
22

3+
import io.swagger.v3.oas.annotations.media.Schema;
34
import lombok.Data;
45

56
import java.util.List;
67

78
@Data
9+
@Schema(description = "카카오 모빌리티 경로 탐색 요청 DTO (경유지 포함)")
810
public class KakaoRouteTransitRequest { //Kakao mobility api에서 경유지 추가 response
911

12+
@Schema(description = "출발지", requiredMode = Schema.RequiredMode.REQUIRED)
1013
private Origin origin;
14+
15+
@Schema(description = "도착지", requiredMode = Schema.RequiredMode.REQUIRED)
1116
private Destination destination;
17+
18+
@Schema(description = "경유지 목록")
1219
private List<Waypoint> waypoints;
1320

21+
22+
@Schema(description = "경로 우선순위", example = "RECOMMEND")
1423
private String priority;
24+
25+
@Schema(description = "차량 연료 타입", example = "GASOLINE")
1526
private String car_fuel;
27+
@Schema(description = "하이패스 여부", example = "true")
28+
1629
private boolean car_hipass;
30+
@Schema(description = "대안 경로 포함 여부", example = "false")
1731
private boolean alternatives;
32+
@Schema(description = "도로 상세 정보 포함 여부", example = "true")
1833
private boolean road_details;
34+
@Schema(description = "summary만 응답 받을지 여부", example = "false")
1935
private boolean summary;
2036

2137
@Data
38+
@Schema(description = "출발지 정보")
2239
public static class Origin {
40+
@Schema(description = "경도(longitude)", example = "126.977969")
2341
private double x;
42+
@Schema(description = "위도(latitude)", example = "37.566535")
2443
private double y;
44+
@Schema(description = "출발 방향 각도(0~359)", example = "0")
2545
private int angle;
2646
}
2747

2848
@Data
49+
@Schema(description = "도착지 정보")
2950
public static class Destination {
51+
@Schema(description = "경도(longitude)", example = "126.986037")
3052
private double x;
53+
@Schema(description = "위도(latitude)", example = "37.563617")
3154
private double y;
3255
}
3356

3457
@Data
58+
@Schema(description = "경유지 정보")
3559
public static class Waypoint {
60+
@Schema(description = "경유지 이름", example = "광화문역")
3661
private String name;
62+
@Schema(description = "경도(longitude)", example = "126.9770")
3763
private double x;
64+
@Schema(description = "위도(latitude)", example = "37.5710")
3865
private double y;
3966
}
4067

0 commit comments

Comments
 (0)