Merge pull request #19 from EWHA-THON-E-BUS/develop

[배포] Stop API 개발 완료, 스웨거 설명 및 주석 추가
E-BUS · Mar 16, 2024 · 97c63bb · 97c63bb
2 parents 5f0e7ff + 6d1e374
commit 97c63bb
Show file tree

Hide file tree

Showing 31 changed files with 714 additions and 6 deletions.
diff --git a/src/main/java/EBus/EBusback/EBusBackApplication.java b/src/main/java/EBus/EBusback/EBusBackApplication.java
@@ -5,8 +5,8 @@
 import org.springframework.cloud.openfeign.EnableFeignClients;
 import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
 
-@EnableJpaAuditing
-@EnableFeignClients
+@EnableJpaAuditing        // createdDate 자동으로 생성하기 위해 필요한 어노테이션
+@EnableFeignClients       // open feign 클라이언트를 사용하기 위해 필요한 어노테이션
 @SpringBootApplication
 public class EBusBackApplication {
 

diff --git a/src/main/java/EBus/EBusback/domain/heart/controller/HeartController.java b/src/main/java/EBus/EBusback/domain/heart/controller/HeartController.java
@@ -7,16 +7,28 @@
 
 import EBus.EBusback.domain.heart.dto.HeartRequestDto;
 import EBus.EBusback.domain.heart.service.HeartService;
+import io.swagger.v3.oas.annotations.Operation;
+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.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
+@Tag(name = "건의해요/고마워요", description = "건의해요/고마워요 글 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/hearts")
 public class HeartController {
 
 	private final HeartService heartService;
 
+	@Operation(summary = "좋아요 등록/취소")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "201", description = "좋아요 등록"),
+		@ApiResponse(responseCode = "201", description = "좋아요 취소"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요"),
+		@ApiResponse(responseCode = "404", description = "해당 id를 갖는 글 없음")
+	})
 	@PostMapping
 	public String clickHeart(@RequestBody @Valid HeartRequestDto requestDto) {
 		return heartService.createOrRemoveHeart(requestDto.getPostId());

diff --git a/src/main/java/EBus/EBusback/domain/heart/service/HeartService.java b/src/main/java/EBus/EBusback/domain/heart/service/HeartService.java
@@ -21,6 +21,7 @@ public class HeartService {
 	private final HeartRepository heartRepository;
 	private final PostRepository postRepository;
 
+	// postId를 id로 가지는 게시글에 좋아요를 등록하거나 취소
 	public String createOrRemoveHeart(Long postId) {
 		Member member = SecurityUtil.getCurrentUser();
 		if (member == null)
@@ -30,9 +31,15 @@ public String createOrRemoveHeart(Long postId) {
 			.orElseThrow(() -> new ResponseStatusException(
 				ErrorCode.NO_POST_EXIST.getStatus(), ErrorCode.NO_POST_EXIST.getMessage()));
 
+		// 사용자가 이 글에 누른 좋아요가 있는지 조회
+		// 있으면 해당 엔티티 가져오고
+		// 없으면 좋아요 생성
 		Heart heart = heartRepository.findByMemberAndPost(member, post)
 			.orElseGet(() -> heartRepository.save(Heart.builder().member(member).post(post).build()));
 
+		// 좋아요 여부를 반대로 변경: true -> false / false -> true
+		// 좋아요를 새로 생성한 경우: 초기 좋아요 여부가 true이면 updateHeart() 메서드 호출 후 좋아요 여부가 false가 되므로
+		// 						초기 좋아요 여부를 false로 설정
 		heart.updateHeart();
 
 		if (heart.getIsValid())

diff --git a/src/main/java/EBus/EBusback/domain/lostItem/controller/LostItemController.java b/src/main/java/EBus/EBusback/domain/lostItem/controller/LostItemController.java
@@ -4,6 +4,10 @@
 import java.time.LocalDate;
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.Operation;
+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.format.annotation.DateTimeFormat;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
@@ -30,13 +34,19 @@
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
+@Tag(name = "분실물", description = "분실물 글 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/items")
 public class LostItemController {
 	private final LostItemService lostItemService;
 	private final S3Uploader s3Uploader;
 
+	@Operation(summary = "분실물 글 등록")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "201", description = "등록 성공"),
+			@ApiResponse(responseCode = "401", description = "로그인 필요")
+	})
 	// 분실물 글 등록
 	@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
 	@ResponseStatus(value = HttpStatus.CREATED)
@@ -49,6 +59,8 @@ public ItemPostResDto createLostItemPost(@RequestPart(value = "image") Multipart
 		return lostItemService.createLostItemPost(writer, imageUrl, itemPostReqDto);
 	}
 
+	@Operation(summary = "분실물 글 검색")
+	@ApiResponse(responseCode = "200", description = "조회 성공")
 	// 분실물 글 검색
 	@GetMapping
 	@ResponseStatus(HttpStatus.OK)
@@ -57,6 +69,13 @@ public List<ItemSearchResDto> getSearchList(@RequestParam(required = false) Stri
 		return lostItemService.getSearchList(keyword, date);
 	}
 
+	@Operation(summary = "분실물 글 삭제")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "삭제 성공"),
+			@ApiResponse(responseCode = "401", description = "로그인 필요"),
+			@ApiResponse(responseCode = "403", description = "작성자 아님"),
+			@ApiResponse(responseCode = "404", description = "해당 id를 갖는 글 없음")
+	})
 	// 분실물 글 삭제
 	@DeleteMapping("/{item_id}")
 	@ResponseStatus(value = HttpStatus.OK)

diff --git a/src/main/java/EBus/EBusback/domain/mainpage/controller/MainPageController.java b/src/main/java/EBus/EBusback/domain/mainpage/controller/MainPageController.java
@@ -2,17 +2,24 @@
 
 import EBus.EBusback.domain.mainpage.dto.MainPageResDto;
 import EBus.EBusback.domain.mainpage.service.MainPageService;
+import io.swagger.v3.oas.annotations.Operation;
+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.HttpStatus;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ResponseStatus;
 import org.springframework.web.bind.annotation.RestController;
 
+@Tag(name = "메인 페이지", description = "메인 페이지 관련 API")
 @RestController
 @RequiredArgsConstructor
 public class MainPageController {
     private final MainPageService mainPageService;
 
+    @Operation(summary = "메인 페이지 글 목록 조회")
+    @ApiResponse(responseCode = "200", description = "조회 성공")
     // 메인 페이지 글 목록 조회
     @GetMapping("/main")
     @ResponseStatus(HttpStatus.OK)

diff --git a/src/main/java/EBus/EBusback/domain/member/controller/AuthController.java b/src/main/java/EBus/EBusback/domain/member/controller/AuthController.java
@@ -10,15 +10,21 @@
 import EBus.EBusback.domain.member.dto.LoginRequestDto;
 import EBus.EBusback.domain.member.dto.LoginResponseDto;
 import EBus.EBusback.domain.member.service.AuthService;
+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;
 
+@Tag(name = "인증", description = "인증 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/auth")
 public class AuthController {
 
 	private final AuthService authService;
 
+	@Operation(summary = "로그인")
+	@ApiResponse(responseCode = "201", description = "로그인 성공")
 	@PostMapping("/login")
 	@ResponseStatus(HttpStatus.CREATED)
 	public LoginResponseDto login(@RequestBody LoginRequestDto requestDto) {

diff --git a/src/main/java/EBus/EBusback/domain/member/controller/MemberController.java b/src/main/java/EBus/EBusback/domain/member/controller/MemberController.java
@@ -7,15 +7,25 @@
 import org.springframework.web.bind.annotation.RestController;
 
 import EBus.EBusback.domain.member.service.MemberService;
+import io.swagger.v3.oas.annotations.Operation;
+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;
 
+@Tag(name = "사용자", description = "사용자 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/members")
 public class MemberController {
 
 	private final MemberService memberService;
 
+	@Operation(summary = "관리자로 전환")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "200", description = "관리자로 전환 성공"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요")
+	})
 	@PatchMapping("/role")
 	@ResponseStatus(HttpStatus.OK)
 	public String changeToAdmin() {

diff --git a/src/main/java/EBus/EBusback/domain/notice/controller/NoticeController.java b/src/main/java/EBus/EBusback/domain/notice/controller/NoticeController.java
@@ -15,34 +15,59 @@
 import EBus.EBusback.domain.notice.dto.NoticeResponseDto;
 import EBus.EBusback.domain.notice.service.NoticeService;
 import EBus.EBusback.domain.post.dto.PostRequestDto;
+import io.swagger.v3.oas.annotations.Operation;
+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.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
+@Tag(name = "공지사항", description = "공지사항 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/notices")
 public class NoticeController {
 
 	private final NoticeService noticeService;
 
+	@Operation(summary = "공지사항 등록")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "201", description = "등록 성공"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요"),
+		@ApiResponse(responseCode = "403", description = "관리자 아님")
+	})
 	@PostMapping
 	@ResponseStatus(HttpStatus.CREATED)
 	public NoticeResponseDto createNotice(@RequestBody @Valid PostRequestDto requestDto) {
 		return noticeService.createNotice(requestDto);
 	}
 
+	@Operation(summary = "공지사항 상세 조회")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "200", description = "조회 성공"),
+		@ApiResponse(responseCode = "404", description = "해당 id를 갖는 글 없음")
+	})
 	@GetMapping("/{noticeId}")
 	@ResponseStatus(HttpStatus.OK)
 	public NoticeResponseDto findNotice(@PathVariable Long noticeId) {
 		return noticeService.findNotice(noticeId);
 	}
 
+	@Operation(summary = "공지사항 리스트 조회")
+	@ApiResponse(responseCode = "200", description = "조회 성공")
 	@GetMapping
 	@ResponseStatus(HttpStatus.OK)
 	public List<NoticeResponseDto> findNoticeList() {
 		return noticeService.findNoticeList();
 	}
 
+	@Operation(summary = "공지사항 삭제")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "200", description = "삭제 성공"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요"),
+		@ApiResponse(responseCode = "403", description = "관리자 아님"),
+		@ApiResponse(responseCode = "404", description = "해당 id를 갖는 글 없음")
+	})
 	@DeleteMapping("/{noticeId}")
 	@ResponseStatus(HttpStatus.OK)
 	public String removeNotice(@PathVariable Long noticeId) {

diff --git a/src/main/java/EBus/EBusback/domain/notice/service/NoticeService.java b/src/main/java/EBus/EBusback/domain/notice/service/NoticeService.java
@@ -24,37 +24,41 @@ public class NoticeService {
 
 	private final NoticeRepository noticeRepository;
 
+	// 공지사항 등록
 	public NoticeResponseDto createNotice(PostRequestDto requestDto) {
 		Member member = SecurityUtil.getCurrentUser();
 		if (member == null)
 			throw new ResponseStatusException(ErrorCode.NON_LOGIN.getStatus(), ErrorCode.NON_LOGIN.getMessage());
-		if (!member.getRole().equals(Role.ADMIN))
+		if (!member.getRole().equals(Role.ADMIN))  // 사용자가 관리자인지 확인
 			throw new ResponseStatusException(ErrorCode.NO_ADMIN.getStatus(), ErrorCode.NO_ADMIN.getMessage());
 		return new NoticeResponseDto(noticeRepository.save(
 			Notice.builder().title(requestDto.getTitle()).content(requestDto.getContent()).writer(member).build()
 		));
 	}
 
+	// noticeId를 id로 가지는 공지사항 상세 조회
 	public NoticeResponseDto findNotice(Long noticeId) {
 		Notice notice = noticeRepository.findById(noticeId)
 			.orElseThrow(() -> new ResponseStatusException(
 				ErrorCode.NO_NOTICE_EXIST.getStatus(), ErrorCode.NO_NOTICE_EXIST.getMessage()));
 		return new NoticeResponseDto(notice);
 	}
 
+	// 공지사항 전체 조회
 	public List<NoticeResponseDto> findNoticeList() {
 		return noticeRepository.findAll().stream()
 			.map(NoticeResponseDto::new).collect(Collectors.toList());
 	}
 
+	// noticeId를 id로 가지는 공지사항 삭제
 	public void removeNotice(Long noticeId) {
 		Member member = SecurityUtil.getCurrentUser();
 		if (member == null)
 			throw new ResponseStatusException(ErrorCode.NON_LOGIN.getStatus(), ErrorCode.NON_LOGIN.getMessage());
 		Notice notice = noticeRepository.findById(noticeId)
 			.orElseThrow(() -> new ResponseStatusException(
 				ErrorCode.NO_NOTICE_EXIST.getStatus(), ErrorCode.NO_NOTICE_EXIST.getMessage()));
-		if (!member.getRole().equals(Role.ADMIN))
+		if (!member.getRole().equals(Role.ADMIN))  // 사용자가 관리자인지 확인
 			throw new ResponseStatusException(ErrorCode.NO_ADMIN.getStatus(), ErrorCode.NO_ADMIN.getMessage());
 		noticeRepository.delete(notice);
 	}

diff --git a/src/main/java/EBus/EBusback/domain/post/controller/PostController.java b/src/main/java/EBus/EBusback/domain/post/controller/PostController.java
@@ -17,46 +17,77 @@
 import EBus.EBusback.domain.post.dto.PostOutlineResponseDto;
 import EBus.EBusback.domain.post.dto.PostRequestDto;
 import EBus.EBusback.domain.post.service.PostService;
+import io.swagger.v3.oas.annotations.Operation;
+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.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
+@Tag(name = "건의해요/고마워요", description = "건의해요/고마워요 글 관련 API")
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/posts")
 public class PostController {
 
 	private final PostService postService;
 
+	@Operation(summary = "건의해요 글 등록")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "201", description = "등록 성공"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요")
+	})
 	@PostMapping("/suggestion")
 	@ResponseStatus(HttpStatus.CREATED)
 	public PostCreateResponseDto createSuggestion(@RequestBody @Valid PostRequestDto requestDto) {
 		return postService.createPost(requestDto, true);
 	}
 
+	@Operation(summary = "고마워요 글 등록")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "201", description = "등록 성공"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요")
+	})
 	@PostMapping("/appreciation")
 	@ResponseStatus(HttpStatus.CREATED)
 	public PostCreateResponseDto createAppreciation(@RequestBody @Valid PostRequestDto requestDto) {
 		return postService.createPost(requestDto, false);
 	}
 
+	@Operation(summary = "건의해요/고마워요 글 상세 조회")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "200", description = "조회 성공"),
+		@ApiResponse(responseCode = "404", description = "해당 id를 갖는 글 없음")
+	})
 	@GetMapping("/{postId}")
 	@ResponseStatus(HttpStatus.OK)
 	public PostDetailResponseDto findPost(@PathVariable Long postId) {
 		return postService.findPost(postId);
 	}
 
+	@Operation(summary = "건의해요 글 리스트 조회")
+	@ApiResponse(responseCode = "200", description = "조회 성공")
 	@GetMapping("/suggestion")
 	@ResponseStatus(HttpStatus.OK)
 	public List<PostOutlineResponseDto> findSuggestionList() {
 		return postService.findPostList(true);
 	}
 
+	@Operation(summary = "고마워요 글 리스트 조회")
+	@ApiResponse(responseCode = "200", description = "조회 성공")
 	@GetMapping("/appreciation")
 	@ResponseStatus(HttpStatus.OK)
 	public List<PostOutlineResponseDto> findAppreciationList() {
 		return postService.findPostList(false);
 	}
 
+	@Operation(summary = "건의해요/고마워요 글 삭제")
+	@ApiResponses(value = {
+		@ApiResponse(responseCode = "200", description = "삭제 성공"),
+		@ApiResponse(responseCode = "401", description = "로그인 필요"),
+		@ApiResponse(responseCode = "403", description = "작성자 아님"),
+		@ApiResponse(responseCode = "404", description = "해당 id를 갖는 글 없음")
+	})
 	@DeleteMapping("/{postId}")
 	@ResponseStatus(HttpStatus.OK)
 	public String removePost(@PathVariable Long postId) {