diff --git a/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsAIController.java b/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsAIController.java index b867f05..7b930d1 100644 --- a/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsAIController.java +++ b/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsAIController.java @@ -2,6 +2,10 @@ import com.lgcns.newspacebackend.domain.news.dto.NewsResponseDto; import com.lgcns.newspacebackend.domain.news.service.NewsAIService; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.http.ResponseEntity; @@ -13,11 +17,13 @@ @RequestMapping("/api/news") @RequiredArgsConstructor @Slf4j +@Tag(name = "NewsAIController - 뉴스데이터 처리를 위한 ai API") public class NewsAIController { private final NewsAIService newsAIService; - + @Operation(summary = "뉴스데이터를 정리해서 보내기위한 ai로직 api" , description = "뉴스데이터를 불러오는 ai 로직 처리") + @Parameter(name = "keyword",description = "탐색하고자 하는 키워드를 받고 객체를 반환합니다.") @GetMapping - public ResponseEntity> getNews(@RequestParam String keyword) { + public ResponseEntity> getNews(@RequestParam(name = "keyword") String keyword) { log.info("[GET] /api/news 요청 - category: {}", keyword); // 요청 로그 try { diff --git a/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsCategoryController.java b/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsCategoryController.java index 6fde0b3..629f9a5 100644 --- a/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsCategoryController.java +++ b/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsCategoryController.java @@ -3,6 +3,10 @@ import com.lgcns.newspacebackend.domain.news.dto.NewsCategoryRequestDto; import com.lgcns.newspacebackend.domain.news.dto.NewsCategoryResponseDto; import com.lgcns.newspacebackend.domain.news.service.NewsCategoryService; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; @@ -12,23 +16,30 @@ @RestController @RequestMapping("/api/news/category") @RequiredArgsConstructor +@Tag(name = "NewsCategoryController - 뉴스 카테고리 CRUD를 위한 API") public class NewsCategoryController { private final NewsCategoryService newsCategoryService; // 카테고리 목록 조회 + @Operation(summary = "뉴스 카테고리를 조회하는 api" , description = "뉴스카테고리 서비스에서 조회 메서드를 수행합니다.") @GetMapping public ResponseEntity> getNewsCategories() { return ResponseEntity.ok(newsCategoryService.getNewsCategories()); } // 카테고리 등록 + @Operation(summary = "뉴스 카테고리를 생성하는 api" , description = "뉴스카테고리 서비스에서 생성 메서드를 수행합니다.") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 뉴스카테고리 정보 Dto") @PostMapping public ResponseEntity createNewsCategory(@RequestBody NewsCategoryRequestDto requestDto) { return ResponseEntity.ok(newsCategoryService.createNewsCategory(requestDto)); } // 카테고리 수정 + @Operation(summary = "뉴스 카테고리를 수정하는 api" , description = "뉴스카테고리 서비스에서 수정 메서드를 수행합니다.") + @Parameter(name = "categoryId",description = "고유성을 부여하기 위해 url에 담기는 카테고리 id") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 뉴스카테고리 정보 Dto") @PutMapping("/{categoryId}") public ResponseEntity updateNewsCategory(@PathVariable Long categoryId, @RequestBody NewsCategoryRequestDto requestDto) { @@ -36,6 +47,8 @@ public ResponseEntity updateNewsCategory(@PathVariable } // 카테고리 삭제 + @Operation(summary = "뉴스 카테고리를 삭제하는 api" , description = "뉴스카테고리 서비스에서 삭제 메서드를 수행합니다.") + @Parameter(name = "categoryId",description = "고유성을 부여하기 위해 url에 담기는 카테고리 id") @DeleteMapping("/{categoryId}") public ResponseEntity deleteNewsCategory(@PathVariable Long categoryId) { newsCategoryService.deleteNewsCategory(categoryId); diff --git a/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsKeywordController.java b/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsKeywordController.java index 45fc35e..1ff0608 100644 --- a/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsKeywordController.java +++ b/src/main/java/com/lgcns/newspacebackend/domain/news/controller/NewsKeywordController.java @@ -3,6 +3,10 @@ import com.lgcns.newspacebackend.domain.news.dto.NewsKeywordRequestDto; import com.lgcns.newspacebackend.domain.news.dto.NewsKeywordResponseDto; import com.lgcns.newspacebackend.domain.news.service.NewsKeywordService; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; @@ -12,23 +16,31 @@ @RestController @RequestMapping("/api/news/keyword") @RequiredArgsConstructor +@Tag(name = "NewsKeywordController - 뉴스 키워드 CRUD를 위한 API") public class NewsKeywordController { private final NewsKeywordService newsKeywordService; // 키워드 목록 조회 - @GetMapping + @Operation(summary = "뉴스 키워드를 조회하는 api" , description = "뉴스키워드 서비스에서 조회 메서드를 수행합니다.") + @GetMapping public ResponseEntity> getNewsKeywords() { return ResponseEntity.ok(newsKeywordService.getNewsKeywords()); } + // 키워드 등록 + @Operation(summary = "뉴스 키워드를 생성하는 api" , description = "뉴스키워드 서비스에서 생성 메서드를 수행합니다.") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 뉴스키워드 정보 Dto") @PostMapping public ResponseEntity createNewsKeyword(@RequestBody NewsKeywordRequestDto requestDto) { return ResponseEntity.ok(newsKeywordService.createNewsKeyword(requestDto)); } // 키워드 수정 + @Operation(summary = "뉴스 키워드를 수정하는 api" , description = "뉴스키워드 서비스에서 수정 메서드를 수행합니다.") + @Parameter(name = "keywordId",description = "고유성을 부여하기 위해 url에 담기는 키워드 id") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 뉴스키워드 정보 Dto") @PutMapping("/{keywordId}") public ResponseEntity updateNewsKeyword(@PathVariable Long keywordId, @RequestBody NewsKeywordRequestDto requestDto) { @@ -36,6 +48,8 @@ public ResponseEntity updateNewsKeyword(@PathVariable Lo } // 키워드 삭제 + @Operation(summary = "뉴스 키워드를 삭제하는 api" , description = "뉴스키워드 서비스에서 삭제 메서드를 수행합니다.") + @Parameter(name = "keywordId",description = "고유성을 부여하기 위해 url에 담기는 키워드 id") @DeleteMapping("/{keywordId}") public ResponseEntity deleteNewsKeyword(@PathVariable Long keywordId) { newsKeywordService.deleteNewsKeyword(keywordId); diff --git a/src/main/java/com/lgcns/newspacebackend/domain/notice/controller/NoticeController.java b/src/main/java/com/lgcns/newspacebackend/domain/notice/controller/NoticeController.java index 234c09e..44395d1 100644 --- a/src/main/java/com/lgcns/newspacebackend/domain/notice/controller/NoticeController.java +++ b/src/main/java/com/lgcns/newspacebackend/domain/notice/controller/NoticeController.java @@ -3,6 +3,10 @@ import com.lgcns.newspacebackend.domain.notice.dto.NoticeRequestDto; import com.lgcns.newspacebackend.domain.notice.dto.NoticeResponseDto; import com.lgcns.newspacebackend.domain.notice.service.NoticeService; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; @@ -10,22 +14,29 @@ @RestController @RequestMapping("/api/notice") @RequiredArgsConstructor +@Tag(name = "NoticeController - 관리자 공지사항 CRUD를 위한 API") public class NoticeController { private final NoticeService noticeService; // 메인화면 공지 조회 + @Operation(summary = "공지사항을 불러오는 api" , description = "공지사항 서비스의 조회 메서드를 수행합니다.") @GetMapping public ResponseEntity getMainNotice() { return ResponseEntity.ok(noticeService.getMainNotice()); } // 공지 등록 + @Operation(summary = "공지사항을 등록하는 api" , description = "공지사항 서비스의 생성 메서드를 수행합니다.") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 공지사항 Dto") @PostMapping public ResponseEntity createNotice(@RequestBody NoticeRequestDto requestDto) { return ResponseEntity.ok(noticeService.createNotice(requestDto)); } // 공지 수정 + @Operation(summary = "공지사항을 수정하는 api" , description = "공지사항 서비스의 수정 메서드를 수행합니다.") + @Parameter(name = "noticeId",description = "고유성을 부여하기 위해 url에 담기는 공지사항 id") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 뉴스키워드 정보 Dto") @PutMapping("/{noticeId}") public ResponseEntity updateNotice(@PathVariable Long noticeId, @RequestBody NoticeRequestDto requestDto) { @@ -33,6 +44,8 @@ public ResponseEntity updateNotice(@PathVariable Long noticeI } // 공지 삭제 + @Operation(summary = "공지사항을 삭제하는 api" , description = "공지사항 서비스의 삭제 메서드를 수행합니다.") + @Parameter(name = "noticeId",description = "고유성을 부여하기 위해 url에 담기는 공지사항 id") @DeleteMapping("/noticeId") public ResponseEntity deleteNotice(@PathVariable Long noticeId) { noticeService.deleteNotice(noticeId); diff --git a/src/main/java/com/lgcns/newspacebackend/domain/user/controller/UserController.java b/src/main/java/com/lgcns/newspacebackend/domain/user/controller/UserController.java index b4ec1b2..71fe5f4 100644 --- a/src/main/java/com/lgcns/newspacebackend/domain/user/controller/UserController.java +++ b/src/main/java/com/lgcns/newspacebackend/domain/user/controller/UserController.java @@ -38,6 +38,7 @@ import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; import jakarta.servlet.http.HttpServletResponse; import lombok.RequiredArgsConstructor; @@ -45,9 +46,9 @@ @Slf4j @RestController -@RequestMapping("/api/user/") @RequiredArgsConstructor -@Tag(name = "UserController - 유저관련 api") +@Tag(name = "UserController - 유저관련 API") +@RequestMapping("/api/user/") public class UserController { @@ -67,9 +68,12 @@ public class UserController * @param userDetails 응답으로 보낼 유저 엔티티입니다. * @return 로그아웃 성공 메시지 */ - @Operation(summary = "로그아웃 api", description = "사용자의 인가를 증명하는 쿠키안의 토큰을 제거하여 로그아웃 상태로 만들어줍니다.") + @Operation(summary = "로그아웃 기능을 수행하는 api", description = "사용자의 인가를 증명하는 쿠키안의 토큰을 제거하여 로그아웃 상태로 만들어줍니다.") + @Parameter(name = "response",description = "Http 요청에 대한 응답 객체") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") @PostMapping("/logout") - public ResponseEntity logout(HttpServletResponse response, + public ResponseEntity logout( + HttpServletResponse response, @AuthenticationPrincipal UserDetailsImpl userDetails) throws Exception { userService.logoutUser(response, userDetails.getUser()); @@ -85,6 +89,8 @@ public ResponseEntity logout(HttpServletResponse response, * @return 회원탈퇴 성공 메시지 */ @Operation(summary = "회원탈퇴 api", description = "현재 인증된 유저를 엔티ㅣ에서 삭제합니다.") + @Parameter(name = "response",description = "Http 요청에 대한 응답 객체") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") @DeleteMapping("/signout") public ResponseEntity deleteUser(HttpServletResponse response, @AuthenticationPrincipal UserDetailsImpl userDetails) throws Exception @@ -101,6 +107,8 @@ public ResponseEntity deleteUser(HttpServletResponse response, * @return UserService.updateProfieImage 메서드에 유저와 파일경로를 반환합니다. */ @Operation(summary = "프로필 이미지 업로드 api", description = "현재 인증된 사용자의 엔티티에 이미지 경로를 저장합니다.") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") + @Parameter(name = "request",description = "Http 요청 객체") @PostMapping(value = "/profile", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) private ResponseEntity createProfileImage(@AuthenticationPrincipal UserDetailsImpl userDetails, MultipartHttpServletRequest request) throws Exception @@ -118,6 +126,8 @@ private ResponseEntity createProfileImage(@AuthenticationPrincipal UserD * @return UserService.updateProfieImage 메서드에 유저와 파일경로를 반환합니다. */ @Operation(summary = "프로필 이미지 수정 api", description = "현재 인증된 사용자 엔티티를 불러와서 수정된 이미지 경로를 저장합니다.") + @Parameter(name = "response",description = "Http 요청에 대한 응답 객체") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") @PutMapping(value = "/profile", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) private ResponseEntity updateProfileImage(@AuthenticationPrincipal UserDetailsImpl userDetails, MultipartHttpServletRequest request) throws Exception @@ -135,6 +145,9 @@ private ResponseEntity updateProfileImage(@AuthenticationPrincipal UserD */ @Operation(summary = "프로필 이미지 삭제 api", description = "현재 인증된 사용자의 엔티티에 이미지 경로를 공백(삭제)상태로 만듭니다.") @DeleteMapping("/profile") + @Parameter(name = "response",description = "Http 요청에 대한 응답 객체") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") + private ResponseEntity deleteProfileImage(@AuthenticationPrincipal UserDetailsImpl userDetails) throws Exception { @@ -149,6 +162,7 @@ private ResponseEntity deleteProfileImage(@AuthenticationPrincipal UserD * @return 이미지가 불러와지면 이미지이름을 확장자 경로로 추가해서 반환, 불러올 이미지가 없을 시 notFound 반환 */ @Operation(summary = "미니 프로필의 이미지 경로를 조회하는 api", description = "현재 인증된 사용자의 엔티티에 이미지 경로를 조회합니다.") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") @GetMapping("/profile") public ResponseEntity getProfileImage(@AuthenticationPrincipal UserDetailsImpl userDetails) throws Exception @@ -181,6 +195,8 @@ public ResponseEntity getProfileImage(@AuthenticationPrincipal UserDet * @return 이미지 형식의 경로를 반환합니다. */ @Operation(summary = "상세페이지의 이미지의 경로를 조회하는 api", description = "현재 인증된 사용자의 상세페이지에서 이미지를 조회합니다.") + @Parameter(name = "day",description = "이미지를 분류 하기위해 폴더 경로중 날짜 폴더가 추가됩니다.") + @Parameter(name = "filename",description = "경로를 다른 Path 경로와 새로운 경로로 만들어줍니다.") @GetMapping("/image/{day}/{filename}") public ResponseEntity getImage(@PathVariable("day") String day, @PathVariable("filename") String filename) throws MalformedURLException @@ -213,6 +229,8 @@ public ResponseEntity getImage(@PathVariable("day") String day, @PathV * @return 회원가입 성공 메시지 리턴 */ @Operation(summary = "회원가입 api", description = "회원가입에 필요한 로직 처리") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 회원가입 정보 Dto") + @Parameter(name = "bindingResult",description = "요청에 대한 데이터 바인딩 결과물") @PostMapping("/signup") public ResponseEntity signup(@Valid @RequestBody SignupRequestDto requestDto, BindingResult bindingResult) throws MethodArgumentNotValidException @@ -228,6 +246,7 @@ public ResponseEntity signup(@Valid @RequestBody SignupRequestDto reques * @return boolean 값에 따른 200 / 400 반환 */ @Operation(summary = "아이디의 중복을 체크하는 api", description = "중복된 유저인지 확인합니다.") + @Parameter(name = "username",description = "유저 id") @GetMapping("/check-id") public ResponseEntity checkId(@RequestParam("username") String username) { @@ -250,6 +269,7 @@ public ResponseEntity checkId(@RequestParam("username") String username) * @return getUserInfo 리턴 */ @Operation(summary = "유저의 정보를 조회하는 api", description = "현재 인증된 사용자 엔티티의 정보를 모두 가져옵니다.") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") @GetMapping("/info") public ResponseEntity getUserInfo(@AuthenticationPrincipal UserDetailsImpl userDetails) { @@ -264,6 +284,8 @@ public ResponseEntity getUserInfo(@AuthenticationPrincipal * @return 200 반환 */ @Operation(summary = "유저 정보를 수정하는 api", description = "현재 인증된 사용자 엔티티의 정보를 수정합니다.") + @Parameter(name = "userDetails",description = "인증된 현재 유저 정보 객체") + @Parameter(name = "requestDto",description = "요청을 보낼때 담기위한 회원가입 정보 Dto") @PatchMapping("/info") public ResponseEntity updateUserInfo(@AuthenticationPrincipal UserDetailsImpl userDetails, @RequestBody UserInfoRequestDto requestDto)