📝 Docs: Swagger 설정 (#31)

* 📝 Docs: Swagger 설정

* 📝 Docs: Auth API 문서 작성

moodoodle-api/build.gradle

@@ -25,6 +25,9 @@ dependencies {
     implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
     implementation 'io.jsonwebtoken:jjwt-impl:0.11.5'
     implementation 'io.jsonwebtoken:jjwt-jackson:0.11.5'
+
+    // swagger
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'
 }
 
 tasks.named('bootJar') {

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/business/AuthFacade.java

@@ -8,8 +8,11 @@
 import zzangdol.moodoodleapi.auth.presentation.dto.request.EmailVerificationRequest;
 import zzangdol.moodoodleapi.auth.presentation.dto.request.SignInRequest;
 import zzangdol.moodoodleapi.auth.presentation.dto.request.SignUpRequest;
+import zzangdol.moodoodleapi.auth.presentation.dto.response.EmailVerificationTokenResponse;
 import zzangdol.moodoodleapi.jwt.JwtResponse;
 import zzangdol.moodoodleapi.jwt.JwtService;
+import zzangdol.moodoodlecommon.exception.custom.MemberCredentialsException;
+import zzangdol.moodoodlecommon.response.status.ErrorStatus;
 import zzangdol.ses.service.AwsSesService;
 
 @Component
@@ -23,16 +26,25 @@ public class AuthFacade {
     private final EmailVerificationTokenService emailVerificationTokenService;
 
     public boolean sendVerificationEmail(String email) {
+        if (!authService.isEmailAvailable(email)) {
+            throw new MemberCredentialsException(ErrorStatus.EMAIL_ALREADY_EXISTS);
+        }
         String verificationCode = verificationCodeService.generateAndSaveCode(email);
         return awsSesService.sendVerificationEmail(email, verificationCode);
     }
 
-    public String verifyEmail(EmailVerificationRequest request) {
+    public EmailVerificationTokenResponse verifyEmail(EmailVerificationRequest request) {
+        if (!authService.isEmailAvailable(request.getEmail())) {
+            throw new MemberCredentialsException(ErrorStatus.EMAIL_ALREADY_EXISTS);
+        }
         verificationCodeService.verifyCode(request.getEmail(), request.getCode());
         return emailVerificationTokenService.generateAndSaveCode(request.getEmail());
     }
 
     public JwtResponse signUp(String emailVerificationToken, SignUpRequest request) {
+        if (!authService.isEmailAvailable(request.getEmail())) {
+            throw new MemberCredentialsException(ErrorStatus.EMAIL_ALREADY_EXISTS);
+        }
         emailVerificationTokenService.verifyToken(request.getEmail(), emailVerificationToken);
         return authService.signUp(request);
     }

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/implement/EmailVerificationTokenService.java

@@ -4,6 +4,7 @@
 import java.util.Base64;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
+import zzangdol.moodoodleapi.auth.presentation.dto.response.EmailVerificationTokenResponse;
 import zzangdol.moodoodlecommon.exception.custom.EmailVerificationTokenException;
 import zzangdol.moodoodlecommon.response.status.ErrorStatus;
 import zzangdol.redis.dao.EmailVerificationTokenRepository;
@@ -15,10 +16,12 @@ public class EmailVerificationTokenService {
 
     private final EmailVerificationTokenRepository emailVerificationTokenRepository;
 
-    public String generateAndSaveCode(String id) {
+    public EmailVerificationTokenResponse generateAndSaveCode(String id) {
         String token = generateSecureToken();
         saveEmailVerificationToken(id, token, 86400L);
-        return token;
+        return EmailVerificationTokenResponse.builder()
+                .emailVerificationToken(token)
+                .build();
     }
 
     private String generateSecureToken() {

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/presentation/AuthController.java

@@ -1,5 +1,8 @@
 package zzangdol.moodoodleapi.auth.presentation;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -12,45 +15,90 @@
 import zzangdol.moodoodleapi.auth.presentation.dto.request.EmailVerificationRequest;
 import zzangdol.moodoodleapi.auth.presentation.dto.request.SignInRequest;
 import zzangdol.moodoodleapi.auth.presentation.dto.request.SignUpRequest;
+import zzangdol.moodoodleapi.auth.presentation.dto.response.EmailVerificationTokenResponse;
+import zzangdol.moodoodleapi.global.annotation.ApiErrorCodeExample;
 import zzangdol.moodoodleapi.jwt.JwtResponse;
-import zzangdol.moodoodlecommon.response.ApiResponse;
+import zzangdol.moodoodlecommon.response.ResponseDto;
+import zzangdol.moodoodlecommon.response.status.ErrorStatus;
 
 @RequiredArgsConstructor
+
+@ApiResponse(responseCode = "2000", description = "성공")
+@Tag(name = "1️⃣ Auth API", description = "인증 API")
 @RequestMapping("/api/auth")
 @RestController
 public class AuthController {
 
     private final AuthFacade authFacade;
 
+    @ApiErrorCodeExample({
+            ErrorStatus.EMAIL_ALREADY_EXISTS,
+            ErrorStatus.INTERNAL_SERVER_ERROR
+    })
+    @Operation(summary = "인증 이메일 발송", description = "지정된 이메일 주소로 인증 이메일을 발송합니다.")
     @PostMapping("/send-verification-email")
-    public ApiResponse<Boolean> sendVerificationEmail(@RequestParam String email) {
-        return ApiResponse.onSuccess(authFacade.sendVerificationEmail(email));
+    public ResponseDto<Boolean> sendVerificationEmail(@RequestParam String email) {
+        return ResponseDto.onSuccess(authFacade.sendVerificationEmail(email));
     }
 
+    @ApiErrorCodeExample({
+            ErrorStatus.TOKEN_INVALID,
+            ErrorStatus.TOKEN_EXPIRED,
+            ErrorStatus.EMAIL_ALREADY_EXISTS,
+            ErrorStatus.INTERNAL_SERVER_ERROR
+    })
+    @Operation(summary = "이메일 검증", description = "제공된 검증 코드로 사용자의 이메일을 검증합니다.")
     @PostMapping("/verify-email")
-    public ApiResponse<String> verifyEmail(@RequestBody EmailVerificationRequest request) {
-        return ApiResponse.onSuccess(authFacade.verifyEmail(request));
+    public ResponseDto<EmailVerificationTokenResponse> verifyEmail(@RequestBody EmailVerificationRequest request) {
+        return ResponseDto.onSuccess(authFacade.verifyEmail(request));
     }
 
+    @ApiErrorCodeExample({
+            ErrorStatus.TOKEN_INVALID,
+            ErrorStatus.MEMBER_NOT_FOUND,
+            ErrorStatus.EMAIL_ALREADY_EXISTS,
+            ErrorStatus.INTERNAL_SERVER_ERROR
+    })
+    @Operation(summary = "사용자 회원가입", description = "이메일 검증 토큰을 사용하여 새로운 사용자를 등록합니다.")
     @PostMapping("/sign-up")
-    public ApiResponse<JwtResponse> signUp(@RequestHeader("X-Email-Verification-Token") String emailVerificationToken,
+    public ResponseDto<JwtResponse> signUp(@RequestHeader("X-Email-Verification-Token") String emailVerificationToken,
                                            @RequestBody SignUpRequest request) {
-        return ApiResponse.onSuccess(authFacade.signUp(emailVerificationToken, request));
+        return ResponseDto.onSuccess(authFacade.signUp(emailVerificationToken, request));
     }
 
+    @ApiErrorCodeExample({
+            ErrorStatus.PASSWORD_MISMATCH,
+            ErrorStatus.MEMBER_NOT_FOUND,
+            ErrorStatus.INTERNAL_SERVER_ERROR
+    })
+    @Operation(summary = "사용자 로그인", description = "사용자를 인증하고 Access Token, Refresh Token을 발급합니다.")
     @PostMapping("/sign-in")
-    public ApiResponse<JwtResponse> signUp(@RequestBody SignInRequest request) {
-        return ApiResponse.onSuccess(authFacade.signIn(request));
+    public ResponseDto<JwtResponse> signUp(@RequestBody SignInRequest request) {
+        return ResponseDto.onSuccess(authFacade.signIn(request));
     }
 
+    @ApiErrorCodeExample({
+            ErrorStatus.MEMBER_NOT_FOUND
+    })
+    @Operation(summary = "이메일 사용 가능 여부 확인", description = "제공된 이메일이 등록에 사용 가능한지 확인합니다.")
     @GetMapping("/check-email")
-    public ApiResponse<Boolean> checkEmailAvailability(@RequestParam String email) {
-        return ApiResponse.onSuccess(authFacade.isEmailAvailable(email));
+    public ResponseDto<Boolean> checkEmailAvailability(@RequestParam String email) {
+        return ResponseDto.onSuccess(authFacade.isEmailAvailable(email));
     }
 
+    @ApiErrorCodeExample({
+            ErrorStatus.REFRESH_TOKEN_NOT_FOUND,
+            ErrorStatus.TOKEN_INVALID,
+            ErrorStatus.TOKEN_EXPIRED,
+            ErrorStatus.TOKEN_UNSUPPORTED,
+            ErrorStatus.TOKEN_CLAIMS_EMPTY,
+            ErrorStatus.MEMBER_NOT_FOUND,
+            ErrorStatus.INTERNAL_SERVER_ERROR
+    })
+    @Operation(summary = "토큰 재발급", description = "Refresh Token, Access Token을 재발급합니다.")
     @PostMapping("/reissue")
-    public ApiResponse<JwtResponse> reissue(@RequestParam String refreshToken) {
-        return ApiResponse.onSuccess(authFacade.reissueToken(refreshToken));
+    public ResponseDto<JwtResponse> reissue(@RequestParam String refreshToken) {
+        return ResponseDto.onSuccess(authFacade.reissueToken(refreshToken));
     }
 
 }

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/presentation/dto/request/EmailVerificationRequest.java

@@ -1,5 +1,6 @@
 package zzangdol.moodoodleapi.auth.presentation.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.NotBlank;
 import lombok.AllArgsConstructor;
@@ -15,9 +16,11 @@ public class EmailVerificationRequest {
 
     @NotBlank(message = "이메일은 필수 입력 값입니다.")
     @Email(message = "유효한 이메일 주소를 입력해주세요.")
+    @Schema(example = "teamzzangdol@gmail.com")
     private String email;
 
     @NotBlank(message = "인증 코드는 필수 입력 값입니다.")
+    @Schema(example = "123456")
     private String code;
 
 }

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/presentation/dto/request/SignInRequest.java

@@ -1,5 +1,6 @@
 package zzangdol.moodoodleapi.auth.presentation.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
@@ -11,7 +12,10 @@
 @AllArgsConstructor
 public class SignInRequest {
 
+    @Schema(example = "teamzzangdol@gmail.com")
     private String email;
+
+    @Schema(example = "password1234")
     private String password;
 
 }

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/presentation/dto/request/SignUpRequest.java

@@ -1,5 +1,6 @@
 package zzangdol.moodoodleapi.auth.presentation.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import java.time.LocalTime;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
@@ -15,9 +16,16 @@
 @AllArgsConstructor
 public class SignUpRequest {
 
+    @Schema(example = "teamzzangdol@gmail.com")
     private String email;
+
+    @Schema(example = "password1234")
     private String password;
+
+    @Schema(example = "짱돌")
     private String nickname;
+
+    @Schema(example = "21:00")
     private LocalTime notificationTime;
 
     public Member toEntity(AuthProvider authProvider, Role role, String encodedPassword) {

moodoodle-api/src/main/java/zzangdol/moodoodleapi/auth/presentation/dto/response/EmailVerificationTokenResponse.java

@@ -1,5 +1,6 @@
 package zzangdol.moodoodleapi.auth.presentation.dto.response;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
@@ -11,6 +12,7 @@
 @AllArgsConstructor
 public class EmailVerificationTokenResponse {
 
+    @Schema(example = "H1i9sNC2DhTcehPkKklwgYrQ5h_b1KwC")
     private String emailVerificationToken;
 
 }

moodoodle-api/src/main/java/zzangdol/moodoodleapi/global/HealthCheckController.java

@@ -0,0 +1,17 @@
+package zzangdol.moodoodleapi.global;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+import zzangdol.moodoodlecommon.response.ResponseDto;
+
+@Hidden
+@RestController
+public class HealthCheckController {
+
+    @GetMapping("/health-check")
+    public ResponseDto<Boolean> healthCheck() {
+        return ResponseDto.onSuccess(Boolean.TRUE);
+    }
+
+}

moodoodle-api/src/main/java/zzangdol/moodoodleapi/global/annotation/ApiErrorCodeExample.java

@@ -0,0 +1,15 @@
+package zzangdol.moodoodleapi.global.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import zzangdol.moodoodlecommon.response.status.ErrorStatus;
+
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ApiErrorCodeExample {
+
+    ErrorStatus[] value();
+
+}

moodoodle-api/src/main/java/zzangdol/moodoodleapi/security/AuthMember.java → moodoodle-api/src/main/java/zzangdol/moodoodleapi/global/annotation/AuthMember.java

@@ -1,4 +1,4 @@
-package zzangdol.moodoodleapi.security;
+package zzangdol.moodoodleapi.global.annotation;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;

moodoodle-api/src/main/java/zzangdol/moodoodleapi/security/AuthenticationArgumentResolver.java → moodoodle-api/src/main/java/zzangdol/moodoodleapi/global/annotation/AuthenticationArgumentResolver.java

@@ -1,4 +1,4 @@
-package zzangdol.moodoodleapi.security;
+package zzangdol.moodoodleapi.global.annotation;
 
 import jakarta.servlet.http.HttpServletRequest;
 import lombok.RequiredArgsConstructor;