Merge pull request #53 from Team-PLAT/docs/#52/swaggerConfig

Author: kyxxgsoo

src/main/java/com/cabin/plat/domain/address/controller/AddressController.java

@@ -6,6 +6,7 @@
 import com.cabin.plat.domain.member.entity.Member;
 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.*;
@@ -21,7 +22,9 @@ public class AddressController {
     @GetMapping("/reverse-geocode")
     public BaseResponse<AddressResponse.AddressString> getAddress(
             @AuthMember Member member,
+            @Parameter(description = "위도 값", example = "36.014188")
             @RequestParam double latitude,
+            @Parameter(description = "경도 값", example = "129.325802")
             @RequestParam double longitude) {
         return BaseResponse.onSuccess(addressService.getAddress(latitude, longitude));
     }

src/main/java/com/cabin/plat/domain/address/dto/AddressResponse.java

@@ -1,5 +1,6 @@
 package com.cabin.plat.domain.address.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.*;
 
 public class AddressResponse {
@@ -8,6 +9,7 @@ public class AddressResponse {
     @Builder
     @AllArgsConstructor
     @NoArgsConstructor
+    @Schema(description = "주소", example = "경상북도 포항시 남구 지곡동")
     public static class AddressString {
         private String address;
     }

src/main/java/com/cabin/plat/domain/member/controller/MemberController.java

@@ -8,6 +8,7 @@
 import com.cabin.plat.domain.member.service.MemberService;
 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.http.MediaType;
@@ -47,7 +48,9 @@ public BaseResponse<MemberResponse.ProfileStreamType> getProfileStreamType(@Auth
     @Operation(summary = "유저 스트리밍 계정 선택 (변경)",
             description = "회원의 스트리밍 계정 정보를 업데이트합니다. `streamType` 파라미터를 통해 새로운 스트리밍 계정 유형을 전달합니다.")
     @PatchMapping("/profile/stream-type")
-    public BaseResponse<MemberResponse.MemberId> updateStreamType(@AuthMember Member member, @RequestParam StreamType streamType) {
+    public BaseResponse<MemberResponse.MemberId> updateStreamType(
+            @AuthMember Member member,
+            @RequestParam StreamType streamType) {
         return BaseResponse.onSuccess(memberService.updateStreamType(member, streamType));
     }
 

src/main/java/com/cabin/plat/domain/member/dto/MemberRequest.java

@@ -1,5 +1,6 @@
 package com.cabin.plat.domain.member.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 import lombok.Getter;
 
@@ -14,6 +15,7 @@ public class MemberRequest {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class Avatar {
+        @Schema(description = "아바타 이미지 URL", defaultValue = "https://example.com/avatar.png")
         private String avatar;
     }
 
@@ -22,7 +24,10 @@ public static class Avatar {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class MemberSignInByEncryptedUserIdentifier {
+        @Schema(description = "암호화된 사용자 식별자", defaultValue = "encryptedUserId123")
         private String encryptedUserIdentifier;
+
+        @Schema(description = "소셜 타입", defaultValue = "APPLE")
         private SocialType socialType;
     }
 
@@ -31,8 +36,13 @@ public static class MemberSignInByEncryptedUserIdentifier {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class MemberAppleSocialSignIn {
+        @Schema(description = "암호화된 사용자 식별자", defaultValue = "encryptedUserId123")
         private String encryptedUserIdentifier;
+
+        @Schema(description = "사용자 전체 이름", defaultValue = "조플랫")
         private String fullName;
+
+        @Schema(description = "사용자 이메일", defaultValue = "[email protected]")
         private String email;
     }
 
@@ -41,6 +51,7 @@ public static class MemberAppleSocialSignIn {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class MemberNickname {
+        @Schema(description = "사용자 닉네임", defaultValue = "plat")
         private String nickname;
     }
 }

src/main/java/com/cabin/plat/domain/member/dto/MemberResponse.java

@@ -1,6 +1,7 @@
 package com.cabin.plat.domain.member.dto;
 
 import com.cabin.plat.domain.member.entity.StreamType;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
@@ -11,26 +12,34 @@ public class MemberResponse {
     @Getter
     @Builder
     public static class ProfileInfo {
+        @Schema(description = "회원의 고유 ID", example = "1")
         private Long memberId;
+
+        @Schema(description = "회원의 닉네임", example = "plat")
         private String nickname;
+
+        @Schema(description = "아바타 이미지 URL", example = "https://example.com/avatar.png")
         private String avatar;
     }
 
     @Getter
     @Builder
     public static class ProfileStreamType {
+        @Schema(description = "회원의 스트리밍 계정 타입", example = "APPLE_MUSIC")
         private StreamType streamType;
     }
 
     @Getter
     @Builder
     public static class MemberId {
+        @Schema(description = "회원의 고유 ID", example = "1")
         private Long memberId;
     }
 
     @Getter
     @Builder
     public static class Avatar {
+        @Schema(description = "아바타 이미지 URL", example = "https://example.com/avatar.png")
         private String avatar;
     }
 
@@ -50,7 +59,10 @@ public static class MemberSignIn {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class MemberTokens {
+        @Schema(description = "엑세스 토큰", example = "eyJhbGciOiJIUzI1NiIsInR...")
         private String accessToken;
+
+        @Schema(description = "리프레시 토큰", example = "eyJhbGciOiJIUzI1NiIsInR...")
         private String refreshToken;
     }
 }

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;
     }
 }