Feature/swagger

src/main/java/com/ODG/ODG_back/controller/MeetingController.java

@@ -4,23 +4,69 @@
 import com.ODG.ODG_back.dto.meeting.response.MeetingCreateResponseDto;
 import com.ODG.ODG_back.dto.meeting.response.MeetingInfoResponseDto;
 import com.ODG.ODG_back.service.MeetingService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/meetings")
 @RequiredArgsConstructor
+@Tag(name = "Meeting", description = "모임 관리 API")
 public class MeetingController {
     private final MeetingService meetingService;
 
+    @Operation(
+            summary = "새 모임 생성",
+            description = "새로운 모임을 생성하고 고유한 링크 코드를 발급합니다. " +
+                    "생성된 링크 코드로 참가자들이 모임에 참여할 수 있습니다." +
+                    "인증이 필요하지 않는 공개 API입니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "모임 생성 성공",
+                    content = @Content(schema = @Schema(implementation = MeetingCreateResponseDto.class))
+            ),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @PostMapping("/")
-    public ResponseEntity<MeetingCreateResponseDto> createMeeting(@RequestBody MeetingCreateRequestDto dto) {
+    public ResponseEntity<MeetingCreateResponseDto> createMeeting(
+            @Parameter(
+                    description = "모임 생성 정보",
+                    required = true,
+                    content = @Content(schema = @Schema(implementation = MeetingCreateRequestDto.class))
+            )@RequestBody MeetingCreateRequestDto dto
+    ) {
         return ResponseEntity.ok(meetingService.addMeeting(dto));
     }
 
+    @Operation(
+            summary = "모임 정보 조회",
+            description = "링크 코드를 사용하여 모임의 기본 정보를 조회합니다. " +
+                    "모임 제목, 목적 정보를 확인할 수 있습니다. " +
+                    "인증이 필요하지 않는 공개 API입니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "모임 정보 조회 성공",
+                    content = @Content(schema = @Schema(implementation = MeetingInfoResponseDto.class))
+            ),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @GetMapping("/{linkCode}/info")
-    public ResponseEntity<MeetingInfoResponseDto> getMeeting(@PathVariable String linkCode) {
+    public ResponseEntity<MeetingInfoResponseDto> getMeeting(
+            @Parameter(description = "모임 링크 코드")
+            @PathVariable String linkCode
+    ) {
         return ResponseEntity.ok(meetingService.getMeeting(linkCode));
     }
 }

src/main/java/com/ODG/ODG_back/controller/MidpointController.java

@@ -1,23 +1,54 @@
 package com.ODG.ODG_back.controller;
 
 import com.ODG.ODG_back.dto.midpoint.response.MidpointResponseDto;
+import com.ODG.ODG_back.security.jwt.JwtTokenProvider;
 import com.ODG.ODG_back.service.MidpointService;
 import com.ODG.ODG_back.strategy.MidpointStrategyType;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/meetings/{inviteCode}/midpoint")
 @RequiredArgsConstructor
+@Tag(name = "Midpoint", description = "중간 지점 추천 API")
 public class MidpointController {
 
     private final MidpointService midpointService;
+    private final JwtTokenProvider jwtTokenProvider;
 
+    @Operation(
+            summary = "중간 지점 조회",
+            description = "모임 참가자들의 위치를 기반으로 중간 지점을 조회합니다. " +
+                    "전략은 쿼리 파라미터로 전달됩니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "중간 지점 조회 성공",
+                    content = @Content(schema = @Schema(implementation = MidpointResponseDto.class))
+            ),
+            @ApiResponse(responseCode = "403", description = "인증 실패 (토큰 없음 또는 유효하지 않음)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @GetMapping
-    public ResponseEntity<MidpointResponseDto> getRecommendedMidpoints(@PathVariable String inviteCode,
-                                                                            @RequestParam MidpointStrategyType strategyType) {
-        return ResponseEntity.ok(midpointService.getRecommendedMidpoints(inviteCode, strategyType));
+    public ResponseEntity<MidpointResponseDto> getRecommendedMidpoints(
+            @Parameter(description = "모임 링크 코드")
+            @PathVariable String inviteCode,
+            @Parameter(description = "JWT 토큰 (쿠키에서 자동 추출, 아무 값 입력)")
+            @CookieValue("access_token") String jwtToken,
+            @Parameter(description = "전략 타입")
+            @RequestParam MidpointStrategyType strategyType) {
+        String userId = jwtTokenProvider.getUserId(jwtToken);
+        return ResponseEntity.ok(midpointService.getRecommendedMidpoints(inviteCode, strategyType, userId));
     }
 
 }

src/main/java/com/ODG/ODG_back/controller/ParticipantController.java

@@ -7,6 +7,13 @@
 import com.ODG.ODG_back.security.jwt.JwtCookieUtil;
 import com.ODG.ODG_back.security.jwt.JwtTokenProvider;
 import com.ODG.ODG_back.service.ParticipantService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -20,14 +27,35 @@
 @RequestMapping("/meetings/{linkCode}/participants")
 @RequiredArgsConstructor
 @Slf4j
+@Tag(name = "Participant", description = "모임 참가자 관리 API")
 public class ParticipantController {
 
     private final ParticipantService participantService;
     private final JwtTokenProvider jwtTokenProvider;
 
+    @Operation(
+            summary = "모임 참가자 등록",
+            description = "모임에 새로운 참가자를 등록하고 JWT 토큰을 쿠키로 설정합니다. " +
+                    "등록 성공 시 access_token 쿠키가 자동으로 브라우저에 저장됩니다. " +
+                    "뿐만 아니라 json으로 access_token을 반환합니다. " +
+                    "인증이 필요한 타 api에선 쿠키에서 access_token을 받으니 유의하십시오. " +
+                    "인증이 필요하지 않는 공개 API입니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "참가자 등록 성공",
+                    content = @Content(schema = @Schema(implementation = ParticipantRegisterResponseDto.class))
+            ),
+            @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터", content = @Content),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @PostMapping("/register")
     public ResponseEntity<ParticipantRegisterResponseDto> addParticipant(
+            @Parameter(description = "모임 링크 코드")
             @PathVariable String linkCode,
+            @Parameter(description = "참가자 등록 정보")
             @RequestBody ParticipantRegisterRequestDto requestDto,
             HttpServletResponse response
     ){
@@ -45,30 +73,77 @@ public ResponseEntity<ParticipantRegisterResponseDto> addParticipant(
         return ResponseEntity.ok(responseDto);
     }
 
+    @Operation(
+            summary = "모임 참가자 삭제",
+            description = "현재 로그인한 참가자를 모임에서 제거합니다. " +
+                    "쿠키의 JWT 토큰을 사용하여 인증을 수행합니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "참가자 삭제 성공"),
+            @ApiResponse(responseCode = "403", description = "인증 실패 (토큰 없음 또는 유효하지 않음)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임 또는 참가자", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @DeleteMapping("/delete")
     public ResponseEntity<Void> deleteParticipant(
+            @Parameter(description = "모임 링크 코드")
             @PathVariable String linkCode,
+            @Parameter(description = "JWT 토큰 (쿠키에서 자동 추출, 아무 값 입력)")
             @CookieValue("access_token") String jwtToken
     ) {
         String userId = jwtTokenProvider.getUserId(jwtToken);
         participantService.deleteParticipant(linkCode, userId);
         return ResponseEntity.ok().build();
     }
 
+    @Operation(
+            summary = "참가자 정보 수정",
+            description = "현재 로그인한 참가자의 정보를 수정합니다. " +
+                    "쿠키의 JWT 토큰을 사용하여 본인 인증을 수행합니다."
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "참가자 정보 수정 성공"),
+            @ApiResponse(responseCode = "403", description = "인증 실패 (토큰 없음 또는 유효하지 않음)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임 또는 참가자", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @PutMapping("/update")
     public ResponseEntity<Void> updateParticipant(
+            @Parameter(description = "모임 링크 코드")
             @PathVariable String linkCode,
+            @Parameter(description = "수정할 참가자 정보")
             @RequestBody ParticipantUpdateRequestDto participantUpdateRequestDto,
+            @Parameter(description = "JWT 토큰 (쿠키에서 자동 추출, 아무 값 입력)")
             @CookieValue("access_token") String jwtToken // 쿠키에서 jwt 추출
     ){
         String userId = jwtTokenProvider.getUserId(jwtToken);
         participantService.modifyParticipant(linkCode, userId, participantUpdateRequestDto);
         return ResponseEntity.ok().build();
     }
 
+    @Operation(
+            summary = "모임 참가자 목록 조회",
+            description = "특정 모임의 모든 참가자 목록과 투표 상태를 조회합니다. "
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "참가자 목록 조회 성공",
+                    content = @Content(schema = @Schema(implementation = ParticipantListResponseDto.class))
+            ),
+            @ApiResponse(responseCode = "403", description = "인증 실패 (토큰 없음 또는 유효하지 않음)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @GetMapping("/")
-    public ResponseEntity<List<ParticipantListResponseDto>> getParticipants(@PathVariable String linkCode){
-        List<ParticipantListResponseDto> participants = participantService.getParticipantsWithVoteStatus(linkCode);
+    public ResponseEntity<List<ParticipantListResponseDto>> getParticipants(
+            @Parameter(description = "모임 링크 코드")
+            @PathVariable String linkCode,
+            @Parameter(description = "JWT 토큰 (쿠키에서 자동 추출, 아무 값 입력)")
+            @CookieValue("access_token") String jwtToken
+    ){
+        String userId = jwtTokenProvider.getUserId(jwtToken);
+        List<ParticipantListResponseDto> participants = participantService.getParticipantsWithVoteStatus(linkCode, userId);
         return ResponseEntity.ok(participants);
     }
 }

src/main/java/com/ODG/ODG_back/controller/PlaceController.java

@@ -1,26 +1,53 @@
 package com.ODG.ODG_back.controller;
 
 import com.ODG.ODG_back.dto.place.response.PlaceResponseDto;
+import com.ODG.ODG_back.security.jwt.JwtTokenProvider;
 import com.ODG.ODG_back.service.PlaceService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
 @RestController
 @RequestMapping("/meetings/{inviteCode}")
 @RequiredArgsConstructor
+@Tag(name = "Place", description = "추천 장소 조회 API")
 public class PlaceController {
 
     private final PlaceService placeService;
+    private final JwtTokenProvider jwtTokenProvider;
 
+    @Operation(
+            summary = "추천 장소 조회",
+            description = "모임 중간 지점을 기반으로 추천 장소 목록을 조회합니다. "
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "추천 장소 조회 성공",
+                    content = @Content(schema = @Schema(implementation = PlaceResponseDto.class))
+            ),
+            @ApiResponse(responseCode = "403", description = "인증 실패 (토큰 없음 또는 유효하지 않음)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "존재하지 않는 모임 또는 중간지점", content = @Content),
+            @ApiResponse(responseCode = "500", description = "서버 내부 오류", content = @Content)
+    })
     @GetMapping("/places")
-    public ResponseEntity<List<PlaceResponseDto>> getPlacesByMidpoint(@PathVariable String inviteCode) {
-        return ResponseEntity.ok(placeService.getPlacesByMidpoint(inviteCode));
+    public ResponseEntity<List<PlaceResponseDto>> getPlacesByMidpoint(
+            @Parameter(description = "모임 초대 코드")
+            @PathVariable String inviteCode,
+            @Parameter(description = "JWT 토큰 (쿠키에서 자동 추출, 아무 값 입력)")
+            @CookieValue("access_token") String jwtToken
+    ) {
+        String userId = jwtTokenProvider.getUserId(jwtToken);
+        return ResponseEntity.ok(placeService.getPlacesByMidpoint(inviteCode, userId));
     }
 
 }