docs: #52 트랙 스웨거 설명 및 기본값 추가

Author: dgh06175

src/main/java/com/cabin/plat/domain/track/controller/TrackController.java

@@ -7,6 +7,7 @@
 import com.cabin.plat.domain.track.service.TrackService;
 import com.cabin.plat.global.common.BaseResponse;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
@@ -22,9 +23,13 @@ public class TrackController {
     @GetMapping("/map")
     public BaseResponse<TrackResponse.TrackMapList> getTracksByLocation(
             @AuthMember Member member,
+            @Parameter(description = "시작 위도 값", example = "36.016512")
             @RequestParam double startLatitude,
+            @Parameter(description = "시작 경도 값", example = "129.321285")
             @RequestParam double startLongitude,
+            @Parameter(description = "끝 위도 값", example = "36.012527")
             @RequestParam double endLatitude,
+            @Parameter(description = "끝 경도 값", example = "129.328229")
             @RequestParam double endLongitude) {
         return BaseResponse.onSuccess(trackService.getTracksByLocation(
                 member,

src/main/java/com/cabin/plat/domain/track/dto/TrackRequest.java

@@ -1,5 +1,7 @@
 package com.cabin.plat.domain.track.dto;
 
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.*;
 
 public class TrackRequest {
@@ -17,10 +19,19 @@ public static class TrackLike {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class TrackUpload {
+        @Schema(description = "isrc", defaultValue = "BRBMG0300729")
         private String isrc;
+
+        @Schema(description = "트랙 이미지 URL", defaultValue = "https://example.com/track.png")
         private String imageUrl;
+
+        @Schema(description = "트랙 게시물 본문", defaultValue = "트랙 게시물 본문입니다.")
         private String content;
+
+        @Schema(description = "트랙 위도 값", defaultValue = "36.014188")
         private double latitude;
+
+        @Schema(description = "트랙 경도 값", defaultValue = "129.325802")
         private double longitude;
     }
 }

src/main/java/com/cabin/plat/domain/track/dto/TrackResponse.java

@@ -1,16 +1,18 @@
 package com.cabin.plat.domain.track.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import java.time.LocalDateTime;
 import java.util.List;
 import lombok.*;
 
-public class TrackResponse {
+    public class TrackResponse {
 
     @Getter
     @Builder
     @AllArgsConstructor
     @NoArgsConstructor
     public static class TrackMapList {
+        @Schema(description = "트랙 리스트")
         private List<TrackMap> tracks;
     }
 
@@ -19,6 +21,7 @@ public static class TrackMapList {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class TrackDetailList {
+        @Schema(description = "트랙 디테일 리스트")
         private List<TrackDetail> trackDetails;
     }
 
@@ -28,10 +31,19 @@ public static class TrackDetailList {
     @NoArgsConstructor
     @EqualsAndHashCode
     public static class TrackMap {
+        @Schema(description = "트랙 고유 ID", example = "1")
         private Long trackId;
+
+        @Schema(description = "트랙 ISRC 코드", example = "isrc2")
         private String isrc;
+
+        @Schema(description = "트랙의 위도", example = "36.015733")
         private Double latitude;
+
+        @Schema(description = "트랙의 경도", example = "129.322700")
         private Double longitude;
+
+        @Schema(description = "좋아요 여부", example = "false")
         private Boolean isLiked;
     }
 
@@ -40,17 +52,40 @@ public static class TrackMap {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class TrackDetail {
+        @Schema(description = "트랙 고유 ID", example = "1")
         private Long trackId;
+
+        @Schema(description = "트랙 ISRC 코드", example = "BRBMG0300729")
         private String isrc;
+
+        @Schema(description = "트랙 생성일", example = "2024-09-07T17:40:43.049879")
         private LocalDateTime createdAt;
+
+        @Schema(description = "트랙의 위도", example = "36.014188")
         private Double latitude;
+
+        @Schema(description = "트랙의 경도", example = "129.325802")
         private Double longitude;
+
+        @Schema(description = "건물 이름", example = "포항공대제1융합관")
         private String buildingName;
+
+        @Schema(description = "주소", example = "경상북도 포항시 남구 지곡동")
         private String address;
+
+        @Schema(description = "트랙 이미지 URL", example = "https://example.com/track.png")
         private String imageUrl;
+
+        @Schema(description = "트랙 내용", example = "트랙 게시물 본문입니다.")
         private String content;
+
+        @Schema(description = "좋아요 수", example = "12")
         private int likeCount;
+
+        @Schema(description = "좋아요 여부", example = "false")
         private Boolean isLiked;
+
+        @Schema(description = "작성자 정보")
         private MemberInfo member;
     }
 
@@ -59,8 +94,13 @@ public static class TrackDetail {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class MemberInfo {
+        @Schema(description = "회원 고유 ID", example = "1")
         private Long memberId;
+
+        @Schema(description = "회원 닉네임", example = "plat")
         private String memberNickname;
+
+        @Schema(description = "회원 아바타 이미지 URL", example = "https://example.com/avatar.png")
         private String avatar;
     }
 
@@ -69,6 +109,7 @@ public static class MemberInfo {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class TrackId {
+        @Schema(description = "트랙 고유 ID", example = "1")
         private Long trackId;
     }
 
@@ -77,6 +118,7 @@ public static class TrackId {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class ReportId {
+        @Schema(description = "리포트 고유 ID", example = "100")
         private Long reportId;
     }
 }