Merge pull request #247 from Step3-kakao-tech-campus/docs/#246

스웨거 API 예외 응답 점검

animory/src/main/java/com/daggle/animory/domain/account/controller/AccountControllerApi.java

@@ -15,7 +15,9 @@
 
 import javax.validation.Valid;
 
-@Tag(name = "계정 API", description = "계정 관련 API 입니다.")
+@Tag(name = "계정 API", description = """
+        최종수정일: 2023-11-06
+    """)
 public interface AccountControllerApi {
 
     @Operation(summary = "보호소 계정으로 회원가입 API", description = "보호소 계정으로 회원가입합니다.")
@@ -34,15 +36,14 @@ public interface AccountControllerApi {
         @ApiResponse(responseCode = "400", description = """
             - ID 또는 Password 불일치로 인한 로그인 실패
             - Email 형식 오류, 비밀번호가 null
-        """, content = @Content),
-        @ApiResponse(responseCode = "404", description = "해당하는 보호소를 찾을 수 없는 경우", content = @Content)
+        """, content = @Content)
     })
     ResponseEntity<Response<AccountLoginSuccessDto>> login(@Valid @RequestBody AccountLoginDto request);
 
     @Operation(summary = "이메일 중복 검증 API", description = "회원가입에 사용할 이메일이 중복되는지 검사합니다.")
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "이메일 중복 검증 성공"),
-        @ApiResponse(responseCode = "400", description = "이미 존재하는 이메일인 경우"),
+        @ApiResponse(responseCode = "400", description = "이미 존재하는 이메일인 경우", content = @Content),
     })
     Response<Void> validateEmail(@Valid @RequestBody EmailValidateDto emailValidateDto);
 }

animory/src/main/java/com/daggle/animory/domain/pet/controller/PetControllerApi.java

@@ -20,9 +20,8 @@
 import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.multipart.MultipartFile;
 
-@Tag(name = "Pet", description = """
-        Pet 등록, 수정 및 조회 관련 API
-        최종수정시각: 2023-10-22 23:56
+@Tag(name = "펫 API", description = """
+        최종수정일: 2023-11-06
     """)
 public interface PetControllerApi {
 
@@ -46,7 +45,7 @@ public interface PetControllerApi {
             "\t\n 3. 빈 이미지 파일일 경우" +
             "\t\n 4. 빈 비디오 파일일 경우" +
             "\t\n 5. 잘못된 나이 형식일 경우", content = @Content),
-        @ApiResponse(responseCode = "404", description = "보호소를 찾을 수 없는 경우", content = @Content),
+        @ApiResponse(responseCode = "404", description = "로그인되어 있는 보호소의 권한 체크 중 해당 보호소를 DB에서 찾을 수 없는 경우", content = @Content),
         @ApiResponse(responseCode = "500", description = "S3 저장 오류", content = @Content)
     })
     Response<RegisterPetSuccessDto> registerPet(
@@ -59,6 +58,8 @@ Response<RegisterPetSuccessDto> registerPet(
     @Operation(summary = "Pet 수정 페이지 진입, 기존 펫 정보 확인",
         description = "Pet 수정 페이지에서, 기존 등록된 정보를 확인하기 위해 호출하는 API 입니다.")
     @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "기존 펫 정보 조회 성공"),
+        @ApiResponse(responseCode = "403", description = "수정 권한이 없는 보호소 계정으로 해당 페이지를 조회 시도한 경우", content = @Content),
         @ApiResponse(responseCode = "404", description = "존재하지 않는 펫인 경우", content = @Content)
     })
     Response<PetRegisterInfoDto> getPetRegisterInfo(UserDetailsImpl userDetails,
@@ -85,7 +86,8 @@ Response<PetRegisterInfoDto> getPetRegisterInfo(UserDetailsImpl userDetails,
             "\t\n 3. 빈 이미지 파일일 경우" +
             "\t\n 4. 빈 비디오 파일일 경우" +
             "\t\n 5. 잘못된 나이 형식일 경우", content = @Content),
-        @ApiResponse(responseCode = "404", description = "존재하지 않는 펫 오류", content = @Content),
+        @ApiResponse(responseCode = "403", description = "해당 펫을 수정할 권한이 없는 경세", content = @Content),
+        @ApiResponse(responseCode = "404", description = "존재하지 않는 펫을 수정하려는 경우", content = @Content),
         @ApiResponse(responseCode = "500", description = "S3 저장 오류", content = @Content)
     })
     Response<UpdatePetSuccessDto> updatePet(
@@ -149,11 +151,13 @@ Response<NewPetProfilesDto> getPetNewProfiles(
     @Operation(summary = "Pet 상세 조회",
         description = "")
     @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "펫 상세 조회 성공"),
         @ApiResponse(responseCode = "404", description = "존재하지 않는 펫인 경우", content = @Content)
     })
     Response<PetDto> getPetDetail(@PathVariable int petId);
 
 
+
     @Operation(summary = "[로그인 필요: 보호소] Pet 입양 완료 처리",
         description = "입양 상태가 변경되고, 보호만료날짜가 삭제됩니다.",
         parameters = {
@@ -167,8 +171,10 @@ Response<NewPetProfilesDto> getPetNewProfiles(
         }
     )
     @ApiResponses(value = {
-        @ApiResponse(responseCode = "404", description = "1. 존재하지 않는 펫인 경우" +
-            "\t\n 2. 보호소를 찾을 수 없는 경우", content = @Content)
+            @ApiResponse(responseCode = "200", description = "펫 입양 처리 성공"),
+            @ApiResponse(responseCode = "403", description = "해당 펫을 수정할 권한이 없는 경우", content = @Content),
+            @ApiResponse(responseCode = "404", description = "1. 존재하지 않는 펫인 경우" +
+            "\t\n 2. 로그인되어 있는 보호소의 권한 체크 중 해당 보호소를 DB에서 찾을 수 없는 경우", content = @Content)
     })
     Response<Void> updatePetAdopted(@AuthenticationPrincipal UserDetailsImpl userDetails,
                                     @PathVariable int petId);

animory/src/main/java/com/daggle/animory/domain/shelter/controller/ShelterControllerApi.java

@@ -23,7 +23,7 @@
 import java.util.List;
 
 @Tag(name = "보호소 API", description = """
-        최종수정시각: 2023-10-22 23:44
+        최종수정일: 2023-11-06
     """)
 public interface ShelterControllerApi {
 
@@ -45,6 +45,10 @@ public interface ShelterControllerApi {
             )
         }
     )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "보호소 프로필 조회 성공"),
+            @ApiResponse(responseCode = "404", description = "해당하는 보호소가 존재하지 않을 경우", content = @Content)
+    })
     @GetMapping("/{shelterId}")
     Response<ShelterProfilePage> getShelter(@PathVariable @Min(0) Integer shelterId,
 
@@ -77,6 +81,11 @@ Response<ShelterProfilePage> getShelter(@PathVariable @Min(0) Integer shelterId,
             )
         )
     )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "보호소 정보 수정 성공"),
+            @ApiResponse(responseCode = "403", description = "내 보호소가 아닌 다른 보호소를 수정하려는 경우 권한 없음으로 예외 발생", content = @Content),
+            @ApiResponse(responseCode = "404", description = "수정하려는 보호소가 애니모리에 등록되있지 않는 경우", content = @Content),
+    })
     @PutMapping("/{shelterId}")
     Response<ShelterUpdateSuccessDto> updateShelter(@AuthenticationPrincipal UserDetailsImpl userDetails,
                                                     @PathVariable @Min(0) Integer shelterId,
@@ -95,10 +104,6 @@ Response<ShelterUpdateSuccessDto> updateShelter(@AuthenticationPrincipal UserDet
             )
         )
     )
-    @ApiResponses(value = {
-        @ApiResponse(responseCode = "200", description = "회원가입 성공"),
-        @ApiResponse(responseCode = "403", description = "내 보호소가 아닌 다른 보호소를 수정하려는 경우 권한이 없다.", content = @Content)
-    })
     @PostMapping("/filter")
     Response<List<ShelterLocationDto>> filterExistShelterListByLocationId(@RequestBody List<Integer> shelterLocationIdList);
 }

animory/src/main/java/com/daggle/animory/domain/shortform/controller/ShortFormControllerApi.java

@@ -9,7 +9,10 @@
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.enums.ParameterIn;
+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 org.springframework.data.domain.Pageable;
 import org.springframework.data.web.PageableDefault;
@@ -18,12 +21,9 @@
 import javax.servlet.http.HttpServletRequest;
 import javax.validation.Valid;
 
-@Tag(
-    name = "숏폼 비디오 API",
-    description = """
-            최종수정시각: 2023-10-22 23:24
-        """
-)
+@Tag(name = "숏폼 API", description = """
+        최종수정일: 2023-11-06
+    """)
 public interface ShortFormControllerApi {
 
     @Operation(summary = "조건부 숏폼 비디오 탐색",
@@ -84,10 +84,43 @@ Response<CategoryShortFormPage> getShortForms(@Parameter(hidden = true)
     @GetMapping("/short-forms/home")
     Response<HomeShortFormPage> getHomeShortForms(@Parameter(hidden = true) @PageableDefault Pageable pageable);
 
+    @Operation(summary = "숏폼 좋아요 등록",
+            description = "특정 숏폼에 좋아요를 등록합니다.",
+            parameters = {
+                @Parameter(
+                    in = ParameterIn.HEADER,
+                    name = "X-Forwarded-For",
+                    description = "클라이언트 IP",
+                    required = true,
+                    schema = @Schema(type = "string", defaultValue = "")
+            )
+        }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "좋아요 삭제 성공"),
+            @ApiResponse(responseCode = "400", description = "헤당하는 Ip로 숏폼에 좋아요가 이미 등록되있는 경우", content = @Content),
+            @ApiResponse(responseCode = "404", description = "해당하는 숏폼이 존재하지 않을 경우", content = @Content)
+    })
     @PostMapping("/like/{petVideoId}")
     Response<Void> increasePetLikeCount(final HttpServletRequest httpServletRequest,
                                         @PathVariable final int petVideoId);
-
+    @Operation(summary = "숏폼 좋아요 삭제",
+            description = "특정 숏폼에 좋아요를 삭제합니다.",
+            parameters = {
+                    @Parameter(
+                            in = ParameterIn.HEADER,
+                            name = "X-Forwarded-For",
+                            description = "클라이언트 IP",
+                            required = true,
+                            schema = @Schema(type = "string", defaultValue = "")
+                    )
+            }
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "좋아요 삭제 성공"),
+            @ApiResponse(responseCode = "400", description = "헤당하는 Ip로 숏폼에 좋아요가 등록되있지 않은 경우", content = @Content),
+            @ApiResponse(responseCode = "404", description = "해당하는 숏폼이 존재하지 않을 경우", content = @Content)
+    })
     @DeleteMapping("/like/{petVideoId}")
     Response<Void> deletePetLikeCount(final HttpServletRequest httpServletRequest, @PathVariable final int petVideoId);
 }