Merge pull request #131 from Team-Smeme/unan#129

[DOCS] Swagger 정보 추가
Team-Smeme · Aug 1, 2023 · 8bf9b14 · 8bf9b14
2 parents e2f3f5c + 6dc4c88
commit 8bf9b14
Show file tree

Hide file tree

Showing 13 changed files with 124 additions and 5 deletions.
diff --git a/src/main/java/com/smeme/server/controller/AuthController.java b/src/main/java/com/smeme/server/controller/AuthController.java
@@ -7,6 +7,9 @@
 import com.smeme.server.service.auth.AuthService;
 import com.smeme.server.util.ApiResponse;
 import com.smeme.server.util.Util;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
@@ -20,10 +23,15 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("api/v2/auth")
+@Tag(name = "Auth", description = "인증/인가 관련 API")
 public class AuthController {
 
     private final AuthService authService;
 
+    @Operation(summary = "소셜 로그인", description = "소셜 로그인을 합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "로그인 성공",
+                    content = @io.swagger.v3.oas.annotations.media.Content(schema = @io.swagger.v3.oas.annotations.media.Schema(implementation = SignInResponseDTO.class)))})
     @PostMapping()
     public ResponseEntity<ApiResponse> signIn(
             @RequestHeader("Authorization") String socialAccessToken,
@@ -33,6 +41,10 @@ public ResponseEntity<ApiResponse> signIn(
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_SIGNIN.getMessage(),response));
     }
 
+    @Operation(summary = "토큰 재발급", description = "토큰을 재발급 받습니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "토큰 재발급 성공",
+                    content = @io.swagger.v3.oas.annotations.media.Content(schema = @io.swagger.v3.oas.annotations.media.Schema(implementation = TokenResponseDTO.class)))})
     @PostMapping("/token")
     public ResponseEntity<ApiResponse> reissueToken(
         Principal principal
@@ -41,6 +53,10 @@ public ResponseEntity<ApiResponse> reissueToken(
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_ISSUE_TOKEN.getMessage(),response));
     }
 
+    @Operation(summary = "로그아웃", description = "로그아웃 합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "로그아웃 성공",
+                    content = @io.swagger.v3.oas.annotations.media.Content(schema = @io.swagger.v3.oas.annotations.media.Schema(implementation = ApiResponse.class)))})
     @PostMapping("/sign-out")
     public ResponseEntity<ApiResponse> signOut(
             Principal principal

diff --git a/src/main/java/com/smeme/server/controller/BadgeController.java b/src/main/java/com/smeme/server/controller/BadgeController.java
@@ -1,8 +1,14 @@
 package com.smeme.server.controller;
 
+import com.smeme.server.dto.badge.BadgeListResponseDTO;
 import com.smeme.server.service.BadgeService;
 import com.smeme.server.util.ApiResponse;
 import com.smeme.server.util.Util;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -11,15 +17,20 @@
 
 import java.security.Principal;
 
-import static com.smeme.server.util.message.ResponseMessage.*;
+import static com.smeme.server.util.message.ResponseMessage.SUCCESS_GET_BADGES;
 
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v2/members/badges")
+@Tag(name = "Badge", description = "뱃지 관련 API")
 public class BadgeController {
 
     private final BadgeService badgeService;
 
+    @Operation(summary = "사용자 뱃지 조회", description = "사용자의 뱃지를 조회합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "뱃지 조회 성공",
+                    content = @Content(schema = @Schema(implementation = BadgeListResponseDTO.class)))})
     @GetMapping
     public ResponseEntity<ApiResponse> getBadgeList(Principal principal) {
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_GET_BADGES.getMessage(), badgeService.getBadgeList(Util.getMemberId(principal))));

diff --git a/src/main/java/com/smeme/server/controller/BetaAuthController.java b/src/main/java/com/smeme/server/controller/BetaAuthController.java
@@ -1,8 +1,12 @@
 package com.smeme.server.controller;
 
 import com.smeme.server.dto.auth.beta.BetaSignInRequestDTO;
+import com.smeme.server.dto.auth.beta.BetaTokenResponseDTO;
 import com.smeme.server.service.auth.BetaAuthService;
 import com.smeme.server.util.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -18,10 +22,15 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/beta")
+@Tag(name = "BetaAuth", description = "베타 테스트용 인증 API")
 public class BetaAuthController {
 
     private final BetaAuthService betaAuthService;
 
+    @Operation(summary = "베타 테스트용 임시 토큰 발급", description = "베타 테스트용 임시 토큰을 발급합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "베타 테스트용 임시 토큰 발급 성공"
+            ,content = @io.swagger.v3.oas.annotations.media.Content(schema = @io.swagger.v3.oas.annotations.media.Schema(implementation = BetaTokenResponseDTO.class)))})
     @PostMapping("/token")
     public ResponseEntity<ApiResponse> getToken(@RequestBody BetaSignInRequestDTO betaSignInRequestDTO) {
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_BETA_AUTH_TOKEN.getMessage(), betaAuthService.createBetaMember(betaSignInRequestDTO)));

diff --git a/src/main/java/com/smeme/server/controller/MemberController.java b/src/main/java/com/smeme/server/controller/MemberController.java
@@ -1,11 +1,19 @@
 package com.smeme.server.controller;
 
+import com.smeme.server.dto.badge.BadgeListResponseDTO;
+import com.smeme.server.dto.member.MemberGetResponseDTO;
 import com.smeme.server.dto.member.MemberNameResponseDTO;
 import com.smeme.server.dto.member.MemberPlanUpdateRequestDTO;
 import com.smeme.server.dto.member.MemberUpdateRequestDTO;
 import com.smeme.server.service.MemberService;
 import com.smeme.server.util.ApiResponse;
 import com.smeme.server.util.Util;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
@@ -18,30 +26,45 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v2/members")
+@Tag(name = "Member", description = "사용자 관련 API")
 public class MemberController {
 
     private final MemberService memberService;
 
+    @Operation(summary = "사용자 정보 수정", description = "사용자의 정보를 수정합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "사용자 정보 수정 성공")})
     @PatchMapping()
     public ResponseEntity<ApiResponse> updateUserProfile(
             Principal principal, @RequestBody MemberUpdateRequestDTO requestDTO) {
         memberService.updateMember(Util.getMemberId(principal), requestDTO);
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_UPDATE_USERNAME.getMessage()));
     }
 
+    @Operation(summary = "사용자 정보 조회", description = "사용자의 정보를 조회합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "사용자 정보 수정 성공"
+            ,content = @Content(schema = @Schema(implementation = MemberGetResponseDTO.class)))})
     @GetMapping("/me")
     public ResponseEntity<ApiResponse> getUserProfile(Principal principal) {
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_GET_USER.getMessage(),memberService.getMember(Util.getMemberId(principal))));
     }
 
+    @Operation(summary = "사용자 학습 계획 변경", description = "사용자의 학습 계획을 변경합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "사용자 학습 계획 성공")})
     @PatchMapping("/plan")
     public ResponseEntity<ApiResponse> updateUserPlan(Principal principal, @Valid @RequestBody MemberPlanUpdateRequestDTO requestDTO) {
         memberService.updateMemberPlan(Util.getMemberId(principal), requestDTO);
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_UPDATE_USER_PLAN.getMessage()));
     }
 
+    @Operation(summary = "닉네임 중복 체크", description = "닉네임 중복 체크를 합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "닉네임 중복 체크 성공"
+                    ,content = @Content(schema = @Schema(implementation = MemberNameResponseDTO.class)))})
     @GetMapping("/nickname/check")
-    public ResponseEntity<ApiResponse> checkDuplicatedName(@RequestParam String name) {
+    public ResponseEntity<ApiResponse> checkDuplicatedName(@Parameter(description = "유저 닉네임") @RequestParam String name) {
         MemberNameResponseDTO response = memberService.checkDuplicatedName(name);
         return ResponseEntity.ok(ApiResponse.success(SUCCESS_CHECK_DUPLICATED_NAME.getMessage(), response));
     }

diff --git a/src/main/java/com/smeme/server/dto/auth/SignInRequestDTO.java b/src/main/java/com/smeme/server/dto/auth/SignInRequestDTO.java
@@ -3,9 +3,15 @@
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.smeme.server.model.SocialType;
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record SignInRequestDTO(
+
+        @Schema(description = "소셜 로그인 타입", example = "KAKAO")
         @JsonProperty("social")
         SocialType socialType,
+
+        @Schema(description = "fcm 토큰", example = "dsdsdsdsds")
         String fcmToken
         ) {
 }
diff --git a/src/main/java/com/smeme/server/dto/auth/SignInResponseDTO.java b/src/main/java/com/smeme/server/dto/auth/SignInResponseDTO.java
@@ -2,15 +2,22 @@
 
 
 import com.smeme.server.dto.badge.BadgeResponseDTO;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 
 import java.util.List;
 
 @Builder
 public record SignInResponseDTO(
+        @Schema(description = "smeme access token", example = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjIyMjU0NjY4LCJleHAiO")
         String accessToken,
+        @Schema(description = "smeme refresh token", example = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjIyMjU0NjY4LCJleHAiO")
         String refreshToken,
+
+        @Schema(description = "회원 등록 여부", example = "true")
         boolean isRegistered,
+
+        @Schema(description = "학습 계획 설정 여부", example = "false")
         boolean hasPlan,
 
         List<BadgeResponseDTO> badges

diff --git a/src/main/java/com/smeme/server/dto/auth/beta/BetaSignInRequestDTO.java b/src/main/java/com/smeme/server/dto/auth/beta/BetaSignInRequestDTO.java
@@ -1,6 +1,9 @@
 package com.smeme.server.dto.auth.beta;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record BetaSignInRequestDTO(
+        @Schema(description = "FCM 토큰", example = "dsdsdsdsds")
         String fcmToken
 ) {
 }
diff --git a/src/main/java/com/smeme/server/dto/auth/beta/BetaTokenResponseDTO.java b/src/main/java/com/smeme/server/dto/auth/beta/BetaTokenResponseDTO.java
@@ -1,10 +1,12 @@
 package com.smeme.server.dto.auth.beta;
 
 import com.smeme.server.dto.badge.BadgeResponseDTO;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 import java.util.List;
 
 public record BetaTokenResponseDTO(
+        @Schema(description = "smeme beta access token", example = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjIyMjU0NjY4LCJleHAiO")
         String accessToken,
         List<BadgeResponseDTO> badges
 ) {

diff --git a/src/main/java/com/smeme/server/dto/badge/BadgeResponseDTO.java b/src/main/java/com/smeme/server/dto/badge/BadgeResponseDTO.java
@@ -2,8 +2,17 @@
 
 import com.smeme.server.model.badge.Badge;
 import com.smeme.server.model.badge.MemberBadge;
+import io.swagger.v3.oas.annotations.media.Schema;
 
-public record BadgeResponseDTO(Long id, String name, String type, String imageUrl) {
+public record BadgeResponseDTO(
+        @Schema(description = "뱃지 id", example = "1")
+        Long id,
+        @Schema(description = "뱃지 이름", example = "연속 3일 일기 뱃지")
+        String name,
+        @Schema(description = "뱃지 타입", example = "STREAK")
+        String type,
+        @Schema(description = "뱃지 이미지 url", example = "https://m.s3.ap-northeast-2.amazonaws.com/badge/streak.png")
+        String imageUrl) {
     public static BadgeResponseDTO of(MemberBadge memberBadge) {
         return new BadgeResponseDTO(memberBadge.getBadge().getId(), memberBadge.getBadge().getName(), memberBadge.getBadge().getType().toString(), memberBadge.getBadge().getImageUrl());
     }

diff --git a/src/main/java/com/smeme/server/dto/member/MemberGetResponseDTO.java b/src/main/java/com/smeme/server/dto/member/MemberGetResponseDTO.java
@@ -4,10 +4,28 @@
 import com.smeme.server.dto.training.TrainingTimeResponseDTO;
 import com.smeme.server.model.Member;
 import com.smeme.server.model.goal.Goal;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 import java.util.List;
 
-public record MemberGetResponseDTO(String username, String target, String way, String detail, String targetLang, boolean hasPushAlarm, TrainingTimeResponseDTO trainingTime, BadgeResponseDTO badge) {
+public record MemberGetResponseDTO(
+        @Schema(description = "회원 아이디", example = "test")
+        String username,
+        @Schema(description = "DEVELOP", example = "영어")
+        String target,
+        @Schema(description = "목표 달성 방법", example = "주 5회 이상 오늘 하루를 돌아보는 일기 작성하기")
+        String way,
+        @Schema(description = "목표 세부 내용", example = "사전 없이 일기 완성\n" +
+                "smeem 연속 일기 배지 획득")
+        String detail,
+        @Schema(description = "목표 언어", example = "en")
+        String targetLang,
+        @Schema(description = "푸시 알림 여부", example = "true")
+        boolean hasPushAlarm,
+        @Schema(description = "학습 시간")
+        TrainingTimeResponseDTO trainingTime,
+        @Schema(description = "뱃지")
+        BadgeResponseDTO badge) {
 
     public static MemberGetResponseDTO of(Goal goal,Member member, TrainingTimeResponseDTO trainingTime, BadgeResponseDTO badge) {
         return new MemberGetResponseDTO(

diff --git a/src/main/java/com/smeme/server/dto/member/MemberNameResponseDTO.java b/src/main/java/com/smeme/server/dto/member/MemberNameResponseDTO.java
@@ -1,4 +1,8 @@
 package com.smeme.server.dto.member;
 
-public record MemberNameResponseDTO(boolean isExist) {
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record MemberNameResponseDTO(
+        @Schema(description = "회원 이름 존재 여부", example = "true")
+        boolean isExist) {
 }
diff --git a/src/main/java/com/smeme/server/dto/member/MemberPlanUpdateRequestDTO.java b/src/main/java/com/smeme/server/dto/member/MemberPlanUpdateRequestDTO.java
@@ -2,10 +2,16 @@
 
 import com.smeme.server.dto.training.TrainingTimeRequestDTO;
 import com.smeme.server.model.goal.GoalType;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 public record MemberPlanUpdateRequestDTO(
+        @Schema(description = "목표 타입", example = "HOBBY")
         GoalType target,
+
+        @Schema(description = "학습 시간")
         TrainingTimeRequestDTO trainingTime,
+
+        @Schema(description = "알람 여부", example = "true")
         boolean hasAlarm
 ) {
 }
diff --git a/src/main/java/com/smeme/server/dto/member/MemberUpdateRequestDTO.java b/src/main/java/com/smeme/server/dto/member/MemberUpdateRequestDTO.java
@@ -1,8 +1,13 @@
 package com.smeme.server.dto.member;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record MemberUpdateRequestDTO(
+        @Schema(description = "회원 이름", example = "홍길동")
         @ValidUsername
         String username,
+
+        @Schema(description = "정책 동의 여부", example = "false")
         boolean termAccepted
 ) {
 }