설명 주석 추가 및 스웨거 문서화 추가 #34

src/main/java/com/urlshortener/actionlog/controller/rest/SystemActionLogRestController.java

@@ -1,8 +1,14 @@
 package com.urlshortener.actionlog.controller.rest;
 
 import com.urlshortener.actionlog.application.SystemActionLogService;
+import com.urlshortener.actionlog.dto.SystemActionLogResponse;
 import com.urlshortener.common.response.ResponseDto;
 import com.urlshortener.shortener.dto.request.ShortCodeRequest;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
@@ -21,9 +27,12 @@ public class SystemActionLogRestController {
     /**
      * 해당 shortCode 의 접근 정보를 전체 조회하는 API
      *
-     * @param shortCode
-     * @return List
+     * @param shortCode 생성헀던 shortCode
+     * @return List<SystemActionLogResponse> 시스템 액션 로그 응답 DTO 반환
      */
+    @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "Short Code 리스트 가져오기 성공",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = SystemActionLogResponse.class))))
+    })
     @GetMapping("/{shortCode}")
     public ResponseEntity<?> getShortUrl(@PathVariable("shortCode") ShortCodeRequest shortCode) {
         var shortcodeLogs = systemActionLogService.getAllShortcodeViews(shortCode);
@@ -34,9 +43,12 @@ public ResponseEntity<?> getShortUrl(@PathVariable("shortCode") ShortCodeRequest
     /**
      * 해당 shortCode 의 조회수를 조회 하는 API
      *
-     * @param shortCode
-     * @return Long
+     * @param shortCode 생성헀던 shortCode
+     * @return Long Short Code 리다이렉션 count
      */
+    @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "Short Code 리다이렉션 Count 가져오기 성공",
+            content = @Content(schema = @Schema(type = "Long")))
+    })
     @GetMapping("/{shortCode}/views")
     public ResponseEntity<?> getShortUrlViewCount(@PathVariable("shortCode") ShortCodeRequest shortCode) {
         var shortcodeViewCount = systemActionLogService.getShortcodeViewCount(shortCode);

src/main/java/com/urlshortener/actionlog/controller/view/SystemActionLogViewController.java

@@ -11,11 +11,21 @@ public class SystemActionLogViewController {
 
     private final SystemActionLogService systemActionLogService;
 
+    /**
+     * 유저의 시스템 액션 로그 게시판 페이지 접속
+     *
+     * @return 시스템 액션 로그 게시판 페이지를 반환합니다.
+     */
     @GetMapping("/history/{shortCode}")
     public String getSystemActionLogViewHome() {
         return "system_action_log_board_page";
     }
 
+    /**
+     * 유저가 생성한 Short Code 페이지 접속
+     *
+     * @return 생성된 Short Code 페이지를 반환합니다.
+     */
     @GetMapping("/logs")
     public String shortcodeTable() {
         return "access_shortcode_page";

src/main/java/com/urlshortener/auth/controller/rest/AuthRestController.java

@@ -1,9 +1,14 @@
 package com.urlshortener.auth.controller.rest;
 
 import com.urlshortener.auth.dto.JoinRequest;
+import com.urlshortener.auth.dto.UserInfoResponse;
 import com.urlshortener.auth.model.AuthUser;
 import com.urlshortener.auth.service.AuthService;
 import com.urlshortener.common.response.ResponseDto;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
@@ -16,13 +21,36 @@
 public class AuthRestController {
     private final AuthService authService;
 
+    /**
+     * 로그인 API
+     *
+     * @param request 로그인 email, password
+     * @return String 유저 JWT 토큰 반환
+     */
+    @ApiResponses(value = {@ApiResponse(responseCode = "201", description = "멤버 로그인 성공 및 토큰 반환",
+            content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(responseCode = "404", description = "해당 유저가 존재하지 않음"),
+            @ApiResponse(responseCode = "400", description = "비밀번호가 맞지 않음"),
+            @ApiResponse(responseCode = "403", description = "토큰 만료"),
+            @ApiResponse(responseCode = "500", description = "JWT 토큰 생성 실패")
+    })
     @PostMapping("/login")
     public ResponseEntity<?> login(@RequestBody JoinRequest request) {
         var userDetail = authService.userLogin(request);
 
         return ResponseDto.created(userDetail);
     }
 
+    /**
+     * 유저 정보 가져오기 API
+     *
+     * @param user 로그인된 유저 ID
+     * @return response 유저 정보 Response
+     */
+    @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "유저 정보 가져오기 성공",
+            content = @Content(schema = @Schema(implementation = UserInfoResponse.class))),
+            @ApiResponse(responseCode = "404", description = "해당 유저가 존재하지 않음"),
+    })
     @GetMapping("/info")
     public ResponseEntity<?> getInformation(AuthUser user) {
         var response = authService.loadUserById(user.getId());

src/main/java/com/urlshortener/auth/token/TokenProvider.java

@@ -1,8 +1,8 @@
 package com.urlshortener.auth.token;
 
+import com.urlshortener.auth.model.AuthToken;
 import com.urlshortener.auth.model.AuthUser;
 import com.urlshortener.auth.model.AuthUserImpl;
-import com.urlshortener.auth.model.AuthToken;
 import com.urlshortener.auth.service.AuthService;
 import com.urlshortener.error.dto.ErrorMessage;
 import com.urlshortener.error.exception.auth.ReadysExpiredJwtException;
@@ -72,7 +72,6 @@ public String generateJwtToken(Long userId, String role) {
      */
     public AuthUser getAuthMember(AuthToken token) {
         var id = getUserToken(token.getToken());
-
         var member = authService.loadUserById(id);
 
         return new AuthUserImpl(member.getId());

src/main/java/com/urlshortener/error/dto/ErrorMessage.java

@@ -8,7 +8,7 @@ public enum ErrorMessage {
     /**
      * 서버 내부 오류
      */
-    INTERNAL_SERVER_ERROR(HttpStatus.BAD_REQUEST, "내부 서버 오류"),
+    INTERNAL_SERVER_ERROR(HttpStatus.INTERNAL_SERVER_ERROR, "내부 서버 오류"),
 
     NOT_FOUND_URL(HttpStatus.NOT_FOUND, "존재하지 않는 url"),
 

src/main/java/com/urlshortener/health/controller/rest/HealthRestController.java

@@ -1,13 +1,22 @@
 package com.urlshortener.health.controller.rest;
 
 import com.urlshortener.common.response.ResponseDto;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 @RestController
 public class HealthRestController {
+
+    /**
+     * 서버 health 확인 요청
+     */
     @GetMapping("/api/v1/health")
+    @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "서버 상태 양호 String 반환"),
+            @ApiResponse(responseCode = "500", description = "웹 서버 내부 에러")
+    })
     public ResponseEntity<?> getHealth() {
         return ResponseDto.ok("health good~~!");
     }

src/main/java/com/urlshortener/member/controller/rest/MemberRestController.java

@@ -2,8 +2,13 @@
 
 import com.urlshortener.common.response.ResponseDto;
 import com.urlshortener.member.domain.dto.request.JoinMemberRequest;
+import com.urlshortener.member.domain.dto.response.MemberResponseDto;
 import com.urlshortener.member.service.MemberService;
 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.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletRequest;
 import lombok.RequiredArgsConstructor;
@@ -22,9 +27,14 @@ public class MemberRestController {
     /**
      * 회원 가입 API
      *
-     * @param request
-     * @return
+     * @param request     회원 가입 email, password
+     * @param httpRequest cookie uuid 조회 및 요청 액션 로그 저장을 위한 Servlet Request
+     * @return member : 생성된 memberId 및 email
      */
+    @ApiResponses(value = {@ApiResponse(responseCode = "201", description = "멤버 회원 가입 성공",
+            content = @Content(schema = @Schema(implementation = MemberResponseDto.class))),
+            @ApiResponse(responseCode = "400", description = "잘못된 회원 가입 정보")
+    })
     @PostMapping
     public ResponseEntity<?> createMember(
             @RequestBody JoinMemberRequest request,
@@ -35,10 +45,15 @@ public ResponseEntity<?> createMember(
     }
 
     /**
+     * 회원가입 Email 중복 확인
+     *
      * @param email : 회원가입 중복확인을 위한 email String
-     * @return boolean 값 리턴. 실패했다면 Exception 발행
+     * @return true 리턴. 실패했다면 Exception 발행
      */
-    @Operation(summary = "중복 이메일 확인", description = "회원 가입 시 회원 이메일 중복 여부를 확인합니다.", tags = {"members"})
+    @Operation(summary = "중복 이메일 확인", description = "회원 가입 시 회원 이메일 중복 여부를 확인", tags = {"members"})
+    @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "이메일 중복 검사 성공"),
+            @ApiResponse(responseCode = "400", description = "이미 존재하는 Email")
+    })
     @GetMapping("/email-check")
     public ResponseEntity<?> checkEmailForSignUp(@RequestParam String email) {
         memberService.duplicateValidationMemberEmail(email);

src/main/java/com/urlshortener/member/controller/view/MemberController.java

@@ -8,6 +8,8 @@
 @Controller
 public class MemberController {
     /**
+     * 로그인 페이지 접속
+     *
      * @return 로그인 화면을 반환합니다.
      */
     @GetMapping("/login")
@@ -16,6 +18,8 @@ public String loginPage() {
     }
 
     /**
+     * 회원가입 페이지 접속
+     *
      * @return 회원가입 화면을 반환합니다.
      */
     @GetMapping("/sign-up")

src/main/java/com/urlshortener/shortener/controller/rest/ShortenerRestController.java

@@ -5,7 +5,14 @@
 import com.urlshortener.ratelimit.annotation.RateLimit;
 import com.urlshortener.shortener.dto.request.OriginUrlRequest;
 import com.urlshortener.shortener.dto.request.ShortCodeRequest;
+import com.urlshortener.shortener.dto.response.ShortCodeAndSystemActionLogResponse;
+import com.urlshortener.shortener.dto.response.ShortCodeResponse;
 import com.urlshortener.shortener.service.ShortenerService;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Nullable;
 import jakarta.servlet.http.HttpServletRequest;
@@ -28,11 +35,16 @@ public class ShortenerRestController {
 
     /**
      * Origin Url 을 Short Url 로 변환하는 API
+     * 인증되지 않은 사용자도 사용 가능
      *
-     * @param originUrlRequest
+     * @param originUrlRequest 요청 받은 원본 URI
+     * @param request          요청 액션 로그 저장을 위한 Servlet Request
      * @return shortUrl 를 반환합니다.
      */
     @RateLimit(type = CREATE_SHORT_URL, value = 10, durationMills = 60000)
+    @ApiResponses(value = {@ApiResponse(responseCode = "201", description = "Origin Url 을 Short Url 로 변환"
+            , content = @Content(schema = @Schema(implementation = ShortCodeResponse.class)))
+    })
     @PostMapping("/api/v1/shorts")
     public ResponseEntity<?> createShortUrl(
             /** 인증되지 않은 사용자도 사용 가능해야 한다. */
@@ -52,10 +64,11 @@ public ResponseEntity<?> createShortUrl(
     /**
      * Short Url 요청을 Origin Url 로 리다이렉트하는 API
      *
-     * @param shortCode
-     * @param response
+     * @param shortCode 요청 받은 최적화 code
+     * @param response  헤더에 값을 넣기 위한 HttpResponse
      * @throws IOException
      */
+    @ApiResponses(value = {@ApiResponse(responseCode = "302", description = "성공적으로 기존 Origin URL 리다이렉션 성공")})
     @GetMapping("/{shortCode}")
     public void getOriginUrl(
             @PathVariable("shortCode") ShortCodeRequest shortCode,
@@ -71,10 +84,13 @@ public void getOriginUrl(
     /**
      * 사용자가 생성했던 shortCode 리스트 반환 API
      *
-     * @param user
-     * @return List
+     * @param user 로그인 유저 정보
+     * @return List 유저가 생성한 url List
      */
     @GetMapping("/api/v1/shorts")
+    @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "로그인 회원의 생성 URL 모두 조회",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ShortCodeAndSystemActionLogResponse.class))))
+    })
     public ResponseEntity<?> findByMemberId(AuthUser user) {
         var result = shortenerService.getFindByMemberId(user);
 

src/main/java/com/urlshortener/shortener/controller/view/ShortenerViewController.java

@@ -8,6 +8,8 @@
 @Controller
 public class ShortenerViewController {
     /**
+     * 메인 페이지 접속
+     *
      * @return 메인 화면을 반환합니다.
      */
     @GetMapping("/main")
@@ -16,6 +18,8 @@ public String page() {
     }
 
     /**
+     * 메인 페이지 접속
+     *
      * @return 메인 화면을 반환합니다.
      */
     @GetMapping("/")
@@ -24,6 +28,8 @@ public String homePage() {
     }
 
     /**
+     * 회원 페이지 접속
+     *
      * @return 회원이 사용하는 화면을 반환합니다.
      */
     @GetMapping("/member_home")