From 0eb726a997b6571e69d33866aaaaece776d38a31 Mon Sep 17 00:00:00 2001 From: 7beunseo Date: Sat, 7 Dec 2024 22:59:05 +0900 Subject: [PATCH 1/6] =?UTF-8?q?=E2=AC=87=EF=B8=8F=20[DOCS]=20UserControlle?= =?UTF-8?q?r=20Swagger=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../backend/controller/docs/UserAPI.java | 179 +++++++++++++++++- 1 file changed, 174 insertions(+), 5 deletions(-) diff --git a/src/main/java/com/carely/backend/controller/docs/UserAPI.java b/src/main/java/com/carely/backend/controller/docs/UserAPI.java index d7d1118..5b8c9b2 100644 --- a/src/main/java/com/carely/backend/controller/docs/UserAPI.java +++ b/src/main/java/com/carely/backend/controller/docs/UserAPI.java @@ -81,19 +81,188 @@ public interface UserAPI { @Operation(summary = "카카오 로그인", description = "카카오 code를 이용한 로그인") ResponseEntity kakaoCallback(@RequestParam("code") String code, HttpServletResponse response) throws IOException; + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "현재 로그인한 유저 정보 조회에 성공한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_USER\", \"message\": \"유저 정보 조회를 성공했습니다.\", \"data\": { \"userId\": 90, \"username\": \"김은서\", \"phoneNum\": \"01082302512\", \"city\": \"성남시 분당구\", \"address\": \"경기도 성남시 분당구 양현로 353\", \"detailAddress\": \"\", \"locationAuthentication\": true, \"userType\": \"VOLUNTEER\", \"shareLocation\": true, \"latitude\": 37.4147451179385, \"longitude\": 127.122162329923, \"age\": 22, \"certificateImage\": \"https://groomcaregiver.s3.ap-northeast-2.amazonaws.com/certificate/image.png\", \"talk\": \"상급\", \"eat\": \"상급\", \"toilet\": \"상급\", \"bath\": \"상급\", \"walk\": \"중급\", \"story\": \"예비 요양보호사로서 책임을 가지고 임하고 있습니다.\", \"guestbookDTOS\": null }}"))), + + @ApiResponse(responseCode = "401", description = "잘못된 토큰으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(name = "INVALID_ACCESS_TOKEN", value = "{ \"status\": 401, \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"유효하지 않은 토큰입니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_EXPIRED", value = "{ \"status\": 401, \"code\": \"TOKEN_EXPIRED\", \"message\": \"토큰이 만료되었습니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_MISSING", value = "{ \"status\": 401, \"code\": \"TOKEN_MISSING\", \"message\": \"요청 헤더에 토큰이 없습니다.\", \"data\": null }") + })), + + @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"code\": \"USER_NOT_FOUND\", \"message\": \"사용자를 찾을 수 없습니다.\", \"data\": null }") + })), + + @ApiResponse(responseCode = "404", description = "존재하지 않는 accessToken으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"error\": \"NOT_FOUND\", \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"존재하지 않는 accessToken입니다.\" }") + })) + }) @Operation(summary = "현재 로그인한 유저 정보 조회하기", description = "현재 로그인한 유저 정보를 조회합니다.") - ResponseEntity getMypage(); + public ResponseEntity getMypage(); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "현재 로그인한 유저 정보 조회에 성공한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_USER\", \"message\": \"유저 정보 조회를 성공했습니다.\", \"data\": { \"userId\": 40, \"username\": \"고은별\", \"phoneNum\": \"010-4567-8901\", \"city\": \"성남시 분당구\", \"address\": \"경기도 성남시 분당구 대장동 산13-2\", \"detailAddress\": \"300호\", \"locationAuthentication\": true, \"userType\": \"VOLUNTEER\", \"shareLocation\": true, \"latitude\": 0, \"longitude\": 0, \"age\": 56, \"certificateImage\": \"https://groomcaregiver.s3.ap-northeast-2.amazonaws.com/certificate/image.png\", \"talk\": \"상급\", \"eat\": \"하급\", \"toilet\": \"하급\", \"bath\": \"중급\", \"walk\": \"중급\", \"story\": \"요양원에서 봉사하며 어르신들에게 필요한 정서적 지원을 하고 있습니다.\", \"guestbookDTOS\": null, \"togetherTime\": 0 }}"))), + + @ApiResponse(responseCode = "401", description = "잘못된 토큰으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(name = "INVALID_ACCESS_TOKEN", value = "{ \"status\": 401, \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"유효하지 않은 토큰입니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_EXPIRED", value = "{ \"status\": 401, \"code\": \"TOKEN_EXPIRED\", \"message\": \"토큰이 만료되었습니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_MISSING", value = "{ \"status\": 401, \"code\": \"TOKEN_MISSING\", \"message\": \"요청 헤더에 토큰이 없습니다.\", \"data\": null }") + })), + + @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"code\": \"USER_NOT_FOUND\", \"message\": \"사용자를 찾을 수 없습니다.\", \"data\": null }") + })), + @ApiResponse(responseCode = "404", description = "존재하지 않는 accessToken으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"error\": \"NOT_FOUND\", \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"존재하지 않는 accessToken입니다.\" }") + })) + }) @Operation(summary = "유저 상세 정보 조회하기", description = "유저의 상세 정보를 조회합니다.") ResponseEntity getDetailUseInfo(@PathVariable("userId") Long userId); - @Operation(summary = "위치 인증 여부 확인하기", description = "사용자가 위치를 인증했는지 확인합니다.") - ResponseEntity verifyAuthentication(); + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 위치 인증 여부를 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_LOCATION_VERIFICATION\", \"message\": \"성공적으로 위치 인증 여부를 조회했습니다.\", \"data\": { \"userId\": 90, \"username\": \"김은서\", \"userType\": \"VOLUNTEER\", \"locationAuthentication\": true }}"))), + + @ApiResponse(responseCode = "401", description = "잘못된 토큰으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(name = "INVALID_ACCESS_TOKEN", value = "{ \"status\": 401, \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"유효하지 않은 토큰입니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_EXPIRED", value = "{ \"status\": 401, \"code\": \"TOKEN_EXPIRED\", \"message\": \"토큰이 만료되었습니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_MISSING", value = "{ \"status\": 401, \"code\": \"TOKEN_MISSING\", \"message\": \"요청 헤더에 토큰이 없습니다.\", \"data\": null }") + })), + + @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"code\": \"USER_NOT_FOUND\", \"message\": \"사용자를 찾을 수 없습니다.\", \"data\": null }") + })), + + @ApiResponse(responseCode = "404", description = "존재하지 않는 accessToken으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"error\": \"NOT_FOUND\", \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"존재하지 않는 accessToken입니다.\" }") + })) + }) + @Operation(summary = "현재 로그인한 유저 위치 인증 여부 조회하기", description = "현재 로그인한 유저의 위치 인증 여부를 조회합니다.") ResponseEntity verifyAuthentication(); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 위치 인증한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_LOCATION_VERIFICATION\", \"message\": \"성공적으로 위치 인증했습니다.\", \"data\": { \"userId\": 90, \"username\": \"김은서\", \"userType\": \"VOLUNTEER\", \"locationAuthentication\": true, \"address\": \"경기도 성남시 분당구 양현로 353\", \"detailAddress\": \"\" }}"))), + + @ApiResponse(responseCode = "401", description = "잘못된 토큰으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(name = "INVALID_ACCESS_TOKEN", value = "{ \"status\": 401, \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"유효하지 않은 토큰입니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_EXPIRED", value = "{ \"status\": 401, \"code\": \"TOKEN_EXPIRED\", \"message\": \"토큰이 만료되었습니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_MISSING", value = "{ \"status\": 401, \"code\": \"TOKEN_MISSING\", \"message\": \"요청 헤더에 토큰이 없습니다.\", \"data\": null }") + })), + + @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"code\": \"USER_NOT_FOUND\", \"message\": \"사용자를 찾을 수 없습니다.\", \"data\": null }") + })), + @ApiResponse(responseCode = "404", description = "존재하지 않는 accessToken으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(value = "{ \"status\": 404, \"error\": \"NOT_FOUND\", \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"존재하지 않는 accessToken입니다.\" }") + })) + }) @Operation(summary = "주소를 전달해 위치 인증하기", description = "주소를 전달해 위치 인증을 진행합니다.") - ResponseEntity verifyAuthenticationPost(@RequestBody() AddressDTO addressDTO); + public ResponseEntity verifyAuthenticationPost(@RequestBody AddressDTO addressDTO); @Operation(summary = "유저 삭제하기", description = "유저를 삭제합니다. (회원 탈퇴로 나중에 수정하기)gi") ResponseEntity deleteUser(@PathVariable String kakao_id) ; -} + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 간병인 추천을 받은 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_USER\", \"message\": \"유저 정보 조회를 성공했습니다.\", \"data\": [ { \"userId\": 91, \"username\": \"이규민\", \"userType\": \"CAREGIVER\", \"timeTogether\": 18, \"address\": \"서울특별시 도봉구 우이천로 394\", \"latitude\": 37.3426052729963, \"longitude\": 127.09922038235, \"km\": 6.163155744795938, \"talk\": \"수월\", \"eat\": \"서투름\", \"toilet\": \"서투름\", \"bath\": \"서투름\", \"walk\": \"서투름\" }, { \"userId\": 61, \"username\": \"윤지인\", \"userType\": \"CAREGIVER\", \"timeTogether\": 0, \"address\": \"경기도 성남시 분당구 동원로1번길 21\", \"latitude\": 37.3902, \"longitude\": 127.1108, \"km\": 0.8939377003160186, \"talk\": \"보통\", \"eat\": \"보통\", \"toilet\": \"보통\", \"bath\": \"서투름\", \"walk\": \"보통\" } ] }"))), + + @ApiResponse(responseCode = "401", description = "요청한 유저가 간병인이 아닌 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 401, \"error\": \"UNAUTHORIZED\", \"code\": \"USER_MUST_NOT_CAREGIVER\", \"message\": \"요청하는 유저가 간병인이어야 합니다.\" }"))), + + @ApiResponse(responseCode = "401", description = "잘못된 토큰으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(name = "INVALID_ACCESS_TOKEN", value = "{ \"status\": 401, \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"유효하지 않은 토큰입니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_EXPIRED", value = "{ \"status\": 401, \"code\": \"TOKEN_EXPIRED\", \"message\": \"토큰이 만료되었습니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_MISSING", value = "{ \"status\": 401, \"code\": \"TOKEN_MISSING\", \"message\": \"요청 헤더에 토큰이 없습니다.\", \"data\": null }") + })) + }) + @Operation(summary = "간병인 유저 추천받기", description = "자원봉사자, 혹은 요양보호사가 간병인을 추천받습니다.") + public ResponseEntity recommandCaregiver(); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 유저 추천을 받은 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_USER\", \"message\": \"유저 정보 조회를 성공했습니다.\", \"data\": [ { \"userId\": 91, \"username\": \"이규민\", \"userType\": \"CARE_WORKER\", \"timeTogether\": 18, \"address\": \"서울특별시 도봉구 우이천로 394\", \"latitude\": 37.3426052729963, \"longitude\": 127.09922038235, \"km\": 6.163155744795938, \"talk\": \"수월\", \"eat\": \"서투름\", \"toilet\": \"서투름\", \"bath\": \"서투름\", \"walk\": \"서투름\" }, { \"userId\": 61, \"username\": \"윤지인\", \"userType\": \"CARE_WORKER\", \"timeTogether\": 0, \"address\": \"경기도 성남시 분당구 동원로1번길 21\", \"latitude\": 37.3902, \"longitude\": 127.1108, \"km\": 0.8939377003160186, \"talk\": \"보통\", \"eat\": \"보통\", \"toilet\": \"보통\", \"bath\": \"서투름\", \"walk\": \"보통\" } ] }"))), + + @ApiResponse(responseCode = "401", description = "요청한 유저가 자원봉사자 혹은 요양보호사가 아닌 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 401, \"error\": \"UNAUTHORIZED\", \"code\": \"USER_MUST_NOT_CAREGIVER\", \"message\": \"요청하는 유저가 자원봉사자 혹은 요양보호사여야 합니다.\" }"))), + + @ApiResponse(responseCode = "401", description = "잘못된 토큰으로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = { + @ExampleObject(name = "INVALID_ACCESS_TOKEN", value = "{ \"status\": 401, \"code\": \"INVALID_ACCESS_TOKEN\", \"message\": \"유효하지 않은 토큰입니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_EXPIRED", value = "{ \"status\": 401, \"code\": \"TOKEN_EXPIRED\", \"message\": \"토큰이 만료되었습니다.\", \"data\": null }"), + @ExampleObject(name = "TOKEN_MISSING", value = "{ \"status\": 401, \"code\": \"TOKEN_MISSING\", \"message\": \"요청 헤더에 토큰이 없습니다.\", \"data\": null }") + })) + }) + @Operation(summary = "자원봉사자, 간병인 유저 추천받기", description = "간병인이 자원봉사자, 혹은 요양보호사를 추천받습니다.") + public ResponseEntity recommendUsers(); + + } From 90706986f9e3ac726cf6d56432a89401112ec48f Mon Sep 17 00:00:00 2001 From: 7beunseo Date: Sat, 7 Dec 2024 23:00:40 +0900 Subject: [PATCH 2/6] =?UTF-8?q?=E2=AC=87=EF=B8=8F=20[DOCS]=20MapController?= =?UTF-8?q?=20Swagger=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../backend/controller/docs/MapAPI.java | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/carely/backend/controller/docs/MapAPI.java b/src/main/java/com/carely/backend/controller/docs/MapAPI.java index 1654cc0..b7ca1e6 100644 --- a/src/main/java/com/carely/backend/controller/docs/MapAPI.java +++ b/src/main/java/com/carely/backend/controller/docs/MapAPI.java @@ -1,15 +1,41 @@ package com.carely.backend.controller.docs; import com.carely.backend.domain.enums.UserType; +import com.carely.backend.dto.response.ErrorResponseDTO; import com.carely.backend.dto.response.ResponseDTO; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +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 org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.RequestParam; import java.util.List; public interface MapAPI { + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 유저 목록을 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_USER\", \"message\": \"유저 정보 조회를 성공했습니다.\", \"data\": [ { \"userId\": 1, \"username\": \"박수정\", \"city\": \"용인시 수지구\", \"address\": \"경기도 용인시 수지구 고기동 15\", \"detailAddress\": \"202호\", \"userType\": \"CAREGIVER\", \"shareLocation\": true, \"latitude\": 37.3418, \"longitude\": 127.0951, \"talk\": \"보통\", \"eat\": \"보통\", \"toilet\": \"서투름\", \"bath\": \"수월\", \"walk\": \"수월\", \"togetherTime\": 0, \"km\": 6.354688064803219 }, { \"userId\": 2, \"username\": \"김영진\", \"city\": \"용인시 수지구\", \"address\": \"경기도 용인시 수지구 고기동 산16-2\", \"detailAddress\": \"202호\", \"userType\": \"CAREGIVER\", \"shareLocation\": true, \"latitude\": 37.342, \"longitude\": 127.0949, \"talk\": \"수월\", \"eat\": \"수월\", \"toilet\": \"보통\", \"bath\": \"서투름\", \"walk\": \"보통\", \"togetherTime\": 0, \"km\": 6.339194156654298 } ] }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 조회 실패한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "404", description = "해당 조건에 맞는 유저를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"USER_NOT_FOUND\", \"message\": \"조건에 맞는 유저를 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "지도에서 유저 목록 조회하기", description = "지도에서 유저 목록을 조회합니다.") - ResponseEntity findUsersByCityAndOptionalUserTypes( + public ResponseEntity findUsersByCityAndOptionalUserTypes( @RequestParam(value = "userType", required = false) List userTypes); + } From 3a2bb44fe0376b874635b0b03322853df987ad91 Mon Sep 17 00:00:00 2001 From: 7beunseo Date: Sat, 7 Dec 2024 23:05:14 +0900 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=9D=20[DOCS]=20ChatController=20Sw?= =?UTF-8?q?agger=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../backend/controller/docs/ChatAPI.java | 59 ++++++++++++++++++- 1 file changed, 56 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/carely/backend/controller/docs/ChatAPI.java b/src/main/java/com/carely/backend/controller/docs/ChatAPI.java index 39801d5..c6cf612 100644 --- a/src/main/java/com/carely/backend/controller/docs/ChatAPI.java +++ b/src/main/java/com/carely/backend/controller/docs/ChatAPI.java @@ -3,9 +3,15 @@ import com.carely.backend.domain.ChatMessageEntity; import com.carely.backend.dto.chat.ChatRequest; import com.carely.backend.dto.chat.ChatRoomResponseDTO; +import com.carely.backend.dto.response.ErrorResponseDTO; import com.carely.backend.dto.response.ResponseDTO; import com.carely.backend.dto.user.CustomUserDetails; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +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 org.springframework.http.ResponseEntity; import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.web.bind.annotation.PathVariable; @@ -16,8 +22,27 @@ import java.util.List; public interface ChatAPI { + @ApiResponses(value = { + @ApiResponse(responseCode = "201", description = "채팅방 생성에 성공한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 201, \"code\": \"SUCCESS_CREATE_CHATROOM\", \"message\": \"채팅방이 성공적으로 생성되었습니다.\", \"data\": { \"id\": 14, \"roomId\": \"ac035619-3602-40e8-8b5f-e7ee68c368a2\", \"user1\": 1, \"user2\": 4, \"lastMessage\": null, \"lastUpdated\": \"2024-11-10T07:10:32.2675425\", \"blocked\": false } }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 채팅방 생성 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "401", description = "인증되지 않은 사용자로 요청할 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 401, \"code\": \"UNAUTHORIZED\", \"message\": \"사용자가 인증되지 않았습니다.\", \"data\": null }"))) + }) @Operation(summary = "채팅방을 생성하기", description = "채팅방을 생성합니다.") - ResponseEntity createRoom(@RequestBody ChatRequest chatRequest); + public ResponseEntity createRoom(@RequestBody ChatRequest chatRequest); @Operation(summary = "메세지 전송하기", description = "메세지를 전송합니다.") ChatMessageEntity sendMessage(ChatMessageEntity chatMessage); @@ -25,8 +50,21 @@ public interface ChatAPI { // @Operation(summary = "채팅을 진행하고 있는 모든 채팅방 조회하기", description = "채팅을 진행하고 있는 모든 채팅방을 조회합니다.") // public ResponseEntity>> findAllChatRooms() ; + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 채팅방 메시지를 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_FIND_CHATROOM\", \"message\": \"모든 채팅방을 조회했습니다.\", \"data\": [ { \"id\": 6, \"type\": \"TALK\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 51, \"message\": \"반가워요\", \"timestamp\": \"2024-11-17T18:15:39.538526\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": false }, { \"id\": 7, \"type\": \"TALK\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 51, \"message\": \"ㅋㅎ\", \"timestamp\": \"2024-11-17T18:15:55.295389\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": false }, { \"id\": 8, \"type\": \"RESERVATION\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 51, \"message\": \"{\\\"id\\\":3,\\\"volunteerId\\\":51,\\\"caregiverId\\\":50,\\\"startTime\\\":\\\"2024-11-17T04:33:06.36\\\",\\\"endTime\\\":\\\"2024-11-17T04:33:06.36\\\",\\\"durationHours\\\":4,\\\"salary\\\":0,\\\"location\\\":\\\"경기도 용인시 수지구 어딘가\\\",\\\"mainTask\\\":\\\"설거지\\\",\\\"volunteerType\\\":\\\"VOLUNTEER_REQUEST\\\",\\\"roomId\\\":\\\"c0babffb-a39b-45e5-b326-a964b49e9409\\\"}\", \"timestamp\": \"2024-11-17T18:30:44.223335\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": true }, { \"id\": 9, \"type\": \"RESERVATION\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 50, \"message\": \"약속을 수락했어요!\", \"timestamp\": \"2024-11-17T18:19:04.822753\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": true }, { \"id\": 23, \"type\": \"FILE\", \"roomId\": \"95c506c0-28f7-4877-80ad-6863ce2e1af9\", \"senderId\": 51, \"message\": \"사진을 보냈습니다.\", \"timestamp\": \"2024-11-17T22:03:20.713524\", \"fileUrl\": \"https://groomcaregiver.s3.ap-northeast-2.amazonaws.com/cbf9f1dc-ff59-41e9-b612-e121eddab16c-KakaoTalk_20241114_101142529.jpg\", \"fileName\": \"KakaoTalk_20241114_101142529.jpg\", \"isApproved\": null } ] }"))), + + @ApiResponse(responseCode = "404", description = "해당 채팅방이 존재하지 않을 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"CHATROOM_NOT_FOUND\", \"message\": \"해당 채팅방을 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "채팅방에 해당하는 메세지 조회하기.", description = "채팅방에 해당하는 메세지들 조회합니다.") - ResponseEntity getMessagesByRoomId(@PathVariable("roomId") String roomId); + public ResponseEntity getMessagesByRoomId(@PathVariable("roomId") String roomId); @Operation(summary = "채팅방 종료하기(웹소켓 close)", description = "채팅방을 종료합니다. 채팅 내역이 더 이상 조회되지 않습니다.") ResponseEntity closeRoom(@PathVariable("roomId") String roomId); @@ -37,6 +75,21 @@ public interface ChatAPI { @Operation(summary = "채팅방에 이미지 전송하기", description = "채팅방에 이미지를 전송합니다.") ResponseEntity uploadFile(@RequestParam("file") MultipartFile file, @PathVariable("roomId") String roomId); + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 열린 채팅방을 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_FIND_CHATROOM\", \"message\": \"모든 채팅방을 조회했습니다.\", \"data\": [ { \"id\": 6, \"type\": \"TALK\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 51, \"message\": \"반가워요\", \"timestamp\": \"2024-11-17T18:15:39.538526\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": false }, { \"id\": 7, \"type\": \"TALK\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 51, \"message\": \"ㅋㅎ\", \"timestamp\": \"2024-11-17T18:15:55.295389\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": false }, { \"id\": 8, \"type\": \"RESERVATION\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 51, \"message\": \"{\\\"id\\\":3,\\\"volunteerId\\\":51,\\\"caregiverId\\\":50,\\\"startTime\\\":\\\"2024-11-17T04:33:06.36\\\",\\\"endTime\\\":\\\"2024-11-17T04:33:06.36\\\",\\\"durationHours\\\":4,\\\"salary\\\":0,\\\"location\\\":\\\"경기도 용인시 수지구 어딘가\\\",\\\"mainTask\\\":\\\"설거지\\\",\\\"volunteerType\\\":\\\"VOLUNTEER_REQUEST\\\",\\\"roomId\\\":\\\"c0babffb-a39b-45e5-b326-a964b49e9409\\\"}\", \"timestamp\": \"2024-11-17T18:30:44.223335\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": true }, { \"id\": 9, \"type\": \"RESERVATION\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\", \"senderId\": 50, \"message\": \"약속을 수락했어요!\", \"timestamp\": \"2024-11-17T18:19:04.822753\", \"fileUrl\": null, \"fileName\": null, \"isApproved\": true }, { \"id\": 23, \"type\": \"FILE\", \"roomId\": \"95c506c0-28f7-4877-80ad-6863ce2e1af9\", \"senderId\": 51, \"message\": \"사진을 보냈습니다.\", \"timestamp\": \"2024-11-17T22:03:20.713524\", \"fileUrl\": \"https://groomcaregiver.s3.ap-northeast-2.amazonaws.com/cbf9f1dc-ff59-41e9-b612-e121eddab16c-KakaoTalk_20241114_101142529.jpg\", \"fileName\": \"KakaoTalk_20241114_101142529.jpg\", \"isApproved\": null } ] }"))), + + @ApiResponse(responseCode = "404", description = "열린 채팅방이 존재하지 않을 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"CHATROOMS_NOT_FOUND\", \"message\": \"열린 채팅방이 존재하지 않습니다.\", \"data\": null }"))) + }) @Operation(summary = "열린 채팅방 조회하기", description = "열린 채팅방을 조회합니다.") - ResponseEntity>> findAllChatRooms(@AuthenticationPrincipal CustomUserDetails user); + public ResponseEntity>> findAllChatRooms( + @AuthenticationPrincipal CustomUserDetails user); + } From 814ed102d0ce0257a796123e1fbe9104f74efe06 Mon Sep 17 00:00:00 2001 From: 7beunseo Date: Sat, 7 Dec 2024 23:10:08 +0900 Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=9D=20[DOCS]=20VolunteerController?= =?UTF-8?q?=20Swagger=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../controller/VolunteerController.java | 25 +++++++ .../backend/controller/docs/VolunteerAPI.java | 72 +++++++++++++++++-- 2 files changed, 93 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/carely/backend/controller/VolunteerController.java b/src/main/java/com/carely/backend/controller/VolunteerController.java index a3d62aa..d2f3e2b 100644 --- a/src/main/java/com/carely/backend/controller/VolunteerController.java +++ b/src/main/java/com/carely/backend/controller/VolunteerController.java @@ -5,6 +5,7 @@ import com.carely.backend.controller.docs.VolunteerAPI; import com.carely.backend.domain.ChatMessageEntity; import com.carely.backend.domain.ChatRoomEntity; +import com.carely.backend.dto.response.ErrorResponseDTO; import com.carely.backend.dto.response.ResponseDTO; import com.carely.backend.dto.volunteer.CreateVolunteerDTO; import com.carely.backend.dto.volunteer.GetVolunteerInfoDTO; @@ -13,6 +14,11 @@ import com.carely.backend.service.VolunteerService; import com.carely.backend.service.chat.ChatService; import com.fasterxml.jackson.databind.ObjectMapper; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +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 lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.messaging.simp.SimpMessagingTemplate; @@ -33,6 +39,25 @@ public class VolunteerController implements VolunteerAPI { private final ObjectMapper objectMapper; private final SimpMessagingTemplate messagingTemplate; + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "성공적으로 자원봉사 요청을 생성한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_CREATE_VOLUNTEER\", \"message\": \"자원봉사 요청을 성공적으로 생성했습니다.\", \"data\": { \"id\": 3, \"volunteerId\": 51, \"caregiverId\": 50, \"startTime\": \"2024-11-17T04:33:06.36\", \"endTime\": \"2024-11-17T04:33:06.36\", \"durationHours\": 4, \"salary\": 0, \"location\": \"경기도 용인시 수지구 어딘가\", \"mainTask\": \"설거지\", \"volunteerType\": \"VOLUNTEER_REQUEST\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\" } }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 자원봉사 요청 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "404", description = "해당 채팅방이나 사용자를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"NOT_FOUND\", \"message\": \"해당 채팅방 또는 사용자를 찾을 수 없습니다.\", \"data\": null }"))) + }) @PostMapping public ResponseEntity createVolunteer(@RequestBody CreateVolunteerDTO dto) { CreateVolunteerDTO.Res res = volunteerService.createVolunteer(dto); diff --git a/src/main/java/com/carely/backend/controller/docs/VolunteerAPI.java b/src/main/java/com/carely/backend/controller/docs/VolunteerAPI.java index 266e15f..8fa8a03 100644 --- a/src/main/java/com/carely/backend/controller/docs/VolunteerAPI.java +++ b/src/main/java/com/carely/backend/controller/docs/VolunteerAPI.java @@ -1,20 +1,84 @@ package com.carely.backend.controller.docs; +import com.carely.backend.dto.response.ErrorResponseDTO; +import com.carely.backend.dto.response.ResponseDTO; import com.carely.backend.dto.volunteer.CreateVolunteerDTO; import com.carely.backend.dto.volunteer.UpdateVolunteerApprovalDTO; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +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 org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestBody; public interface VolunteerAPI { + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 자원봉사 요청을 생성한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_CREATE_VOLUNTEER\", \"message\": \"자원봉사 요청을 성공적으로 생성했습니다.\", \"data\": { \"id\": 3, \"volunteerId\": 51, \"caregiverId\": 50, \"startTime\": \"2024-11-17T04:33:06.36\", \"endTime\": \"2024-11-17T04:33:06.36\", \"durationHours\": 4, \"salary\": 0, \"location\": \"경기도 용인시 수지구 어딘가\", \"mainTask\": \"설거지\", \"volunteerType\": \"VOLUNTEER_REQUEST\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\" } }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 자원봉사 요청 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "404", description = "해당 채팅방이나 사용자를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"NOT_FOUND\", \"message\": \"해당 채팅방 또는 사용자를 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "자원봉사 요청하기", description = "채팅방에서 자원봉사를 요청합니다.") - ResponseEntity createVolunteer(@RequestBody CreateVolunteerDTO dto) ; + public ResponseEntity createVolunteer(@RequestBody CreateVolunteerDTO dto); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 자원봉사 요청을 승인한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_APPROVAL\", \"message\": \"자원봉사 요청을 성공적으로 승인했습니다.\", \"data\": { \"id\": 3, \"volunteerId\": 51, \"caregiverId\": 50, \"startTime\": \"2024-11-17T04:33:06.36\", \"endTime\": \"2024-11-17T04:33:06.36\", \"durationHours\": 4, \"salary\": 0, \"location\": \"경기도 용인시 수지구 어딘가\", \"mainTask\": \"설거지\", \"volunteerType\": \"VOLUNTEER_REQUEST\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\" } }"))), + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 자원봉사 승인 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "404", description = "해당 자원봉사 요청을 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"VOLUNTEER_NOT_FOUND\", \"message\": \"해당 자원봉사 요청을 찾을 수 없습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "403", description = "승인 권한이 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 403, \"code\": \"FORBIDDEN\", \"message\": \"자원봉사 요청을 승인할 권한이 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "자원봉사 승인하기", description = "간병인이 채팅방에서 자원봉사를 승인합니다.") - ResponseEntity approveVolunteer(@PathVariable("volunteerId") Long volunteerId, - @RequestBody() UpdateVolunteerApprovalDTO updateVolunteerApprovalDTO) throws Exception; + public ResponseEntity approveVolunteer(@PathVariable("volunteerId") Long volunteerId, + @RequestBody() UpdateVolunteerApprovalDTO updateVolunteerApprovalDTO) throws Exception; + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 자원봉사 요청 상세 정보를 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_VOLUNTEER\", \"message\": \"자원봉사 요청을 성공적으로 조회했습니다.\", \"data\": { \"id\": 5, \"volunteerId\": 51, \"volunteerName\": \"김은서\", \"volunteerAge\": 0, \"phoneNum\": \"string\", \"address\": \"뒷골 1로 42\", \"startTime\": \"2024-11-17T04:33:06.36\", \"endTime\": \"2024-11-17T04:33:06.36\", \"durationHours\": 4, \"salary\": 0, \"location\": \"경기도 용인시 수지구 어딘가\", \"mainTask\": \"설거지\", \"volunteerType\": \"VOLUNTEER_REQUEST\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\" } }"))), + @ApiResponse(responseCode = "404", description = "해당 자원봉사 요청을 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"VOLUNTEER_NOT_FOUND\", \"message\": \"해당 자원봉사 요청을 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "자원봉사 상세보기", description = "자원봉사자, 혹은 요양보호사가 간병인에게 요청한 자원봉사를 조회합니다.") - ResponseEntity getVolunteerInfo(@PathVariable("volunteerId") Long volunteerId) ; + public ResponseEntity getVolunteerInfo(@PathVariable("volunteerId") Long volunteerId); } From f0ac696aefa12fa5eaf003cca9c288a4cfea3a2e Mon Sep 17 00:00:00 2001 From: 7beunseo Date: Sat, 7 Dec 2024 23:14:07 +0900 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=93=9D=20[DOCS]=20NewsController=20Sw?= =?UTF-8?q?agger=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../backend/controller/docs/NewsAPI.java | 80 ++++++++++++++++++- 1 file changed, 76 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/carely/backend/controller/docs/NewsAPI.java b/src/main/java/com/carely/backend/controller/docs/NewsAPI.java index 337b56e..2ff161d 100644 --- a/src/main/java/com/carely/backend/controller/docs/NewsAPI.java +++ b/src/main/java/com/carely/backend/controller/docs/NewsAPI.java @@ -2,23 +2,95 @@ import com.carely.backend.dto.news.CreateCommentDTO; import com.carely.backend.dto.news.CreateNewsDTO; +import com.carely.backend.dto.response.ErrorResponseDTO; import com.carely.backend.dto.response.ResponseDTO; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +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 jakarta.validation.Valid; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestBody; public interface NewsAPI { + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 소식 목록을 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_NEWS\", \"message\": \"소식을 성공적으로 조회했습니다.\", \"data\": [ { \"newsId\": 2, \"title\": \"오늘 아침은 유난히 쌀쌀했네요.\", \"content\": \"오늘 아침은 유난히 쌀쌀했네요. 환자분께서 밤새 잠을 잘 못 주무셨다고 하셔서, 아침 식사 후에 가벼운 스트레칭을 도와드렸습니다. 조금씩 기분이 좋아지시는 모습에 보람을 느꼈습니다. 이런 작은 변화들이 참 감사하게 느껴지는 하루였습니다.\", \"writerType\": \"VOLUNTEER\", \"writer\": \"서유나\", \"commentCount\": 0, \"createdAt\": \"2024-12-01T07:10:01\" }, { \"newsId\": 3, \"title\": \"우리 같이걸음 멤버들 덕분에 요즘 큰 힘을 얻고 있습니다.\", \"content\": \"우리 같이걸음 멤버들 덕분에 요즘 큰 힘을 얻고 있습니다. 산책도 좋았지만, 무엇보다 따뜻한 대화가 더 의미 있었어요. 다음 모임에서는 제가 준비한 작은 간식을 나누고 싶습니다.\", \"writerType\": \"CAREGIVER\", \"writer\": \"박은영\", \"commentCount\": 0, \"createdAt\": \"2024-12-01T07:10:01\" }, { \"newsId\": 4, \"title\": \"며칠 전 철수 님과 함께 걸었던 길이 자꾸 떠오릅니다.\", \"content\": \"며칠 전 철수 님과 함께 걸었던 길이 자꾸 떠오릅니다. 이야기를 나누는 동안 마음이 참 편안했고, 오랜만에 기분 좋은 산책을 했습니다. 다음에도 다 같이 모여 걸을 수 있는 날을 기다립니다.\", \"writerType\": \"VOLUNTEER\", \"writer\": \"정지우\", \"commentCount\": 0, \"createdAt\": \"2024-12-01T07:10:01\" }, { \"newsId\": 5, \"title\": \"오늘은 스스로를 위해 시간을 조금 내어 동네 공원을 다녀왔습니다.\", \"content\": \"간병을 하다 보면 가끔씩 마음이 무겁게 느껴질 때가 있는데, 오늘은 스스로를 위해 시간을 조금 내어 동네 공원을 다녀왔습니다. 걸으며 생각을 정리하고 나니 다시 에너지가 채워지는 느낌입니다. 간병도 중요하지만, 저 자신도 돌보는 하루가 되어야겠다고 생각했습니다.\", \"writerType\": \"CAREGIVER\", \"writer\": \"김민주\", \"commentCount\": 0, \"createdAt\": \"2024-12-01T07:10:01\" } ] }"))), + + @ApiResponse(responseCode = "404", description = "해당 groupId에 해당하는 소식 목록을 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"GROUP_NOT_FOUND\", \"message\": \"해당 groupId에 해당하는 소식 목록을 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "groupId에 해당하는 소식 목록 보기", description = "groupId에 해당하는 소식 목록을 조회합니다.") - ResponseEntity getGroupNewsList(@PathVariable("groupId") Long groupId); + public ResponseEntity getGroupNewsList(@PathVariable("groupId") Long groupId); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 소식 상세 정보를 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_NEWS\", \"message\": \"소식을 성공적으로 조회했습니다.\", \"data\": { \"newsId\": 1, \"title\": \"그의 편지, 남겨진 따뜻한 기억\", \"content\": \"우연히 회사 이메일을 확인하다 받은 그의편지.\\n\\n칭찬교직원 고객의소리 였다.\\n\\n의료진의 칭찬을 도모하기위해 고객의 소리(건의함)에 입원환자,진료환자는 불만,칭찬,건의를 할수 있는 제도이다.\\n\\n건당 1만원씩 주기도 했었고(지금은 잠정중단)\\n\\n개인메일로 어떤환자가 어떤글을 썼는지 알수있다\\n\\n엄마는 입원할때마다 내이름을 적어내며 나에게 조금이라도 도움이 되었으면 ..하셨었다\\n\\n여느칭찬카드와 달리 그의 이름 석자를 보자마자 나는 순간멈칫했다.\\n\\n‘하늘나라에 잘\", \"writerType\": \"VOLUNTEER\", \"writer\": \"김세훈\", \"commentCount\": null, \"createdAt\": \"2024-12-01T07:09:00\", \"newsComments\": [ { \"newsCommentId\": 3, \"content\": \"첫 모임에 참석했던 날이 아직도 기억나요. 낯설고 어색했던 제게 다들 따뜻하게 대해주셔서 정말 놀랐습니다.\\n\\n그 이후로 제 삶에서 우리돌봄이는 없어서는 안 될 존재가 되었어요. 여러분 덕분에 저는 오늘도 하루를 잘 버텨내고 있습니다. 정말 고맙습니다.\", \"writerType\": \"CAREGIVER\", \"writer\": \"유진호\", \"createdAt\": \"2024-12-01T07:09:46\" }, { \"newsCommentId\": 1, \"content\": \"최근에 한 환자분이 퇴원하면서 건넨 짧은 편지가 계속 마음에 남습니다.\\n\\n덕분에 힘들지만 평온하게 퇴원합니다. 감사합니다.\\n\\n간병은 때로는 고되고 지치지만, 이런 짧은 감사의 표현이 모든 것을 잊게 만들더군요.\\n\\n우리 함께 이 길을 걸으며 서로에게 힘이 되어줍시다.\", \"writerType\": \"CARE_WORKER\", \"writer\": \"박진우\", \"createdAt\": \"2024-12-01T07:09:46\" }, { \"newsCommentId\": 2, \"content\": \"며칠 전 모임에서 나눴던 이야기들이 계속 생각나네요. 특히 민철 씨가 어머니를 간병하며 경험했던 이야기는 큰 울림을 주었어요. 우리 모두가 이렇게 서로를 지지하고 격려하며 함께 나아가니 참 감사하다는 생각이 듭니다.\", \"writerType\": \"CAREGIVER\", \"writer\": \"박수정\", \"createdAt\": \"2024-12-01T07:09:46\" } ] } }"))), + @ApiResponse(responseCode = "404", description = "해당 소식을 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"NEWS_NOT_FOUND\", \"message\": \"해당 소식을 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "소식 상세보기", description = "소식에 달린 답글과 함께 소식을 조회합니다.") - ResponseEntity getNewsDetail(@PathVariable("newsId") Long newsId); + public ResponseEntity getNewsDetail(@PathVariable("newsId") Long newsId); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 소식을 생성한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_CREATE_NEWS\", \"message\": \"소식을 성공적으로 생성했습니다.\", \"data\": { \"newsId\": null, \"title\": \"신영이가 쓰는 소식\", \"content\": \"우헤헤\", \"writer\": \"강신영\", \"createdAt\": \"2024-12-03T11:54:46.716401011\" } }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 소식 생성 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + @ApiResponse(responseCode = "404", description = "해당 groupId를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"GROUP_NOT_FOUND\", \"message\": \"해당 groupId를 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "소식 생성하기", description = "소식을 생성합니다.") - ResponseEntity> createNews(@PathVariable("groupId") Long groupId, @Valid @RequestBody CreateNewsDTO createNewsDTO); + public ResponseEntity> createNews(@PathVariable("groupId") Long groupId, @Valid @RequestBody CreateNewsDTO createNewsDTO); + + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 소식 댓글을 생성한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_CREATE_NEWS_COMMENT\", \"message\": \"소식 댓글을 성공적으로 생성했습니다.\", \"data\": { \"commentId\": null, \"content\": \"신영이가 쓰는 댓글\", \"writer\": \"강신영\", \"createdAt\": \"2024-12-03T11:58:27.252507299\" } }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 댓글 생성 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))), + + @ApiResponse(responseCode = "404", description = "해당 newsId를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"NEWS_NOT_FOUND\", \"message\": \"해당 소식을 찾을 수 없습니다.\", \"data\": null }"))) + }) @Operation(summary = "소식에 댓글 남기기", description = "소식에 댓글을 남깁니다.") - ResponseEntity> createNewsComment(@PathVariable("newsId") Long newsId, @Valid @RequestBody CreateCommentDTO createNewsDTO); + public ResponseEntity> createNewsComment(@PathVariable("newsId") Long newsId, @Valid @RequestBody CreateCommentDTO createNewsDTO); + } From f606f99acd8aaf95a9ce7b5c1f199c391c8d126a Mon Sep 17 00:00:00 2001 From: 7beunseo Date: Sat, 7 Dec 2024 23:18:47 +0900 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=93=9D=20[DOCS]=20MemoController=20Sw?= =?UTF-8?q?agger=20=EB=AC=B8=EC=84=9C=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../backend/controller/docs/MemoAPI.java | 45 ++++++++++++++++++- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/carely/backend/controller/docs/MemoAPI.java b/src/main/java/com/carely/backend/controller/docs/MemoAPI.java index 44c32b9..d871a44 100644 --- a/src/main/java/com/carely/backend/controller/docs/MemoAPI.java +++ b/src/main/java/com/carely/backend/controller/docs/MemoAPI.java @@ -1,22 +1,63 @@ package com.carely.backend.controller.docs; import com.carely.backend.dto.memo.CreateMemoDTO; +import com.carely.backend.dto.response.ErrorResponseDTO; import com.carely.backend.dto.response.ResponseDTO; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; +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 org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestBody; public interface MemoAPI { - @Operation(summary = "방명록 작성하기(메모)", description = "방명록을 작성합니다. 작성한 방명록은 ai가 요약합니다.") + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 메모를 작성한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_CREATE_MEMO\", \"message\": \"메모를 성공적으로 작성했습니다.\", \"data\": { \"memoId\": 33, \"content\": \"오늘 오전 9시에 체온을 측정했으며, 37.2도로 약간의 열이 있습니다. 환자가 식사를 절반 정도만 드셨고, 평소보다 식욕이 떨어진 모습을 보였습니다. 약물 복용은 오전 8시 정시에 완료되었으며, 부작용은 없습니다. 배변은 하루 두 번으로 정상적인 상태를 보였지만, 약간의 변비 증상이 있습니다. 오늘 물리치료 중 걸음걸이가 이전보다 조금 더 안정적이었습니다. 손님(보호자)이 오후 3시에 방문하여 환자와 약 1시간 동안 대화를 나눴습니다. 환자가 오른쪽 무릎 통증을 호소하여 보호자에게 보고 후 추가 검사 필요성을 전달했습니다. 교대 시, 환자가 밤사이에 불안감을 느껴 잠을 제대로 못 잤다는 점을 다음 간병인에게 알렸습니다. 오전 목욕을 진행했으며, 대상자가 상쾌하다는 반응을 보였습니다. 환자가 '손자가 보고 싶다'라고 말씀하셔서 보호자와 영상통화를 도와드렸습니다.\", \"writerName\": \"김은서\", \"all\": \"환자의 체온은 37.2도로 약간의 열이 있습니다. 변비 증상이 있으나 배변은 정상 범위를 유지하고 있습니다. 식사량은 평소와 비슷합니다. 약물 복용은 정상적으로 이루어졌으며 부작용은 없습니다. 물리치료를 통해 걸음걸이가 안정적으로 개선되었습니다. 수면에 어려움을 겪고 있습니다. 오른쪽 무릎에 통증이 있어 추가 검사가 필요합니다. 배뇨는 하루에 세 번으로 정상입니다.\", \"healthy\": \"환자의 체온은 37.2도입니다.\", \"eat\": \"환자는 식사량을 평소와 비슷하게 유지하고 있습니다. 약물 복용은 정상적으로 이루어졌으며 부작용은 없습니다.\", \"additionalHealth\": \"오른쪽 무릎에 통증이 있어 추가 검사가 필요합니다.\", \"social\": \"환자는 손자와의 영상통화를 통해 대화를 나누었습니다.\", \"voiding\": \"배변이 정상적으로 이루어졌습니다.\" } }"))), + + @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터로 메모 생성 실패", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 400, \"code\": \"INVALID_REQUEST\", \"message\": \"요청 데이터가 잘못되었습니다.\", \"data\": null }"))) + }) + @Operation(summary = "방명록 작성하기(메모)", description = "방명록을 작성합니다. 작성한 방명록은 AI가 요약합니다.") ResponseEntity createMemo(@RequestBody CreateMemoDTO createMemoDTO); // @Operation(summary = "방명록 조회하기", description = "다른 유저가 작성한 방명록을 조회합니다.") // public ResponseEntity getMemoList(@PathVariable("userId") Long userId); + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 자원봉사 요청 상세 정보를 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_VOLUNTEER\", \"message\": \"자원봉사 요청을 성공적으로 조회했습니다.\", \"data\": { \"id\": 5, \"volunteerId\": 51, \"volunteerName\": \"김은서\", \"volunteerAge\": 0, \"phoneNum\": \"string\", \"address\": \"뒷골 1로 42\", \"startTime\": \"2024-11-17T04:33:06.36\", \"endTime\": \"2024-11-17T04:33:06.36\", \"durationHours\": 4, \"salary\": 0, \"location\": \"경기도 용인시 수지구 어딘가\", \"mainTask\": \"설거지\", \"volunteerType\": \"VOLUNTEER_REQUEST\", \"roomId\": \"c0babffb-a39b-45e5-b326-a964b49e9409\" } }"))), + + }) @Operation(summary = "메모를 작성하지 않은 약속 조회하기", description = "메모를 작성하지 않은 약속 조회하기") ResponseEntity getNotWrittenVolunteer(); - @Operation(summary = "유저의 요약된 메모 조회하기", description = "유저의 요약된 메모 조회하기") + @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "성공적으로 메모를 조회한 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 200, \"code\": \"SUCCESS_RETRIEVE_MEMO\", \"message\": \"성공적으로 메모를 조회했습니다.\", \"data\": [ { \"memoId\": 32, \"content\": \"오늘 오전 9시에 체온을 측정했으며, 37.2도로 약간의 열이 있습니다. 환자가 식사를 절반 정도만 드셨고, 평소보다 식욕이 떨어진 모습을 보였습니다...\", \"writerName\": \"김은서\", \"all\": \"환자의 체온은 37.2도로 약간의 열이 있습니다...\", \"healthy\": \"환자의 체온은 37.2도로 약간의 열이 있습니다.\", \"eat\": \"식욕은 감소하였으나 식사량은 평소와 비슷하며, 영양 보충제도 섭취하였습니다...\", \"additionalHealth\": \"변비 증상이 있으나 배변은 정상 범위를 유지하고 있습니다.\", \"social\": \"수면에 어려움을 겪고 있으며 오른쪽 무릎 통증으로 추가 검사가 필요합니다...\", \"voiding\": null } ] }"))), + + @ApiResponse(responseCode = "404", description = "해당 userId를 찾을 수 없는 경우", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = ErrorResponseDTO.class), + examples = @ExampleObject(value = + "{ \"status\": 404, \"code\": \"USER_NOT_FOUND\", \"message\": \"해당 유저를 찾을 수 없습니다.\", \"data\": null }"))), + }) + @Operation(summary = "유저의 요약된 메모 조회하기", description = "유저의 요약된 메모 조회합니다.") ResponseEntity getRecentMemo(@PathVariable("userId") Long userId); + }