fix:swagger명세 추가, post /vote 수정

Author: eastlight82

docs

@@ -0,0 +1,22 @@
+# Notes: Spec ↔ Implementation 매핑
+#
+# page#0 관리자 페이지
+# 0.1 홈화면
+# GET /votes : 목록 (id, name, code, adminUrl, shareUrl)
+    투표 블록 터치 → GET /votes/{id} 로 상세 조회
+# POST /votes : 새 투표 생성 (res.shareUrl 로 링크 복사)
+    날짜 2개 선택 → backend에는 startDate,endDate로 저장 (두 날짜 포함 범위)
+    프론트에서 3번째 날짜 선택 시 프론트 로직으로 2개만 유지 → 서버엔 항상 (start,end)만 전달
+# DELETE /votes/{id} : 투표 삭제
+# PATCH /votes/{id} : 이름/날짜 범위 수정 (둘 다 vote attr)
+
+#
+# 0.2 투표 설정 화면
+# 참여자 칩 생성 섹션: POST /votes/{id}/participants {displayName}
+    생성된 응답에 loginCode 포함(칩/매직링크 구현용)
+# 참여자 삭제: DELETE /participants/{participantId}
+#
+# 기타
+# Vote 삭제 시 @OneToMany(cascade=ALL, orphanRemoval=true)로 참가자 함께 삭제
+# 코드/링크: app.base-url + "/v/" + code (공유 링크), "/admin/votes/{id}" (관리 URL)
+# Validation: endDate >= startDate. name not blank.

docs.txt

@@ -17,6 +17,11 @@ public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                 .formLogin(form -> form.disable())  // 기본 로그인 폼 비활성화
                 .httpBasic(basic -> basic.disable()) // 브라우저 팝업 로그인 비활성화
                 .authorizeHttpRequests(auth -> auth
+                        .requestMatchers(
+                                "/v3/api-docs/**",
+                                "/swagger-ui/**",
+                                "/swagger-ui.html"
+                        ).permitAll()
                         .anyRequest().permitAll()
                 );
 

src/main/java/com/workingdead/config/SecurityConfig.java

@@ -4,11 +4,15 @@
 import com.workingdead.meet.entity.*;
 import com.workingdead.meet.repository.*;
 import com.workingdead.meet.service.*;
+import io.swagger.v3.oas.annotations.*;
+import io.swagger.v3.oas.annotations.media.*;
+import io.swagger.v3.oas.annotations.responses.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
-
+@Tag(name = "Participant", description = "참여자 관리 API")
 @RestController
 @RequestMapping("")
 public class ParticipantController {
@@ -17,13 +21,30 @@ public class ParticipantController {
 
 
     // 0.2 참여자 추가/삭제
+    @Operation(
+            summary = "참여자 추가",
+            description = "특정 투표에 새로운 참여자를 추가합니다. displayName을 기반으로 참여자 칩이 생성됩니다."
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "참여자 추가 성공",
+                    content = @Content(schema = @Schema(implementation = ParticipantDtos.ParticipantRes.class))),
+            @ApiResponse(responseCode = "400", description = "잘못된 요청 (displayName이 비어있는 경우)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "투표를 찾을 수 없음", content = @Content)
+    })
     @PostMapping("/votes/{voteId}/participants")
     public ResponseEntity<ParticipantDtos.ParticipantRes> add(@PathVariable Long voteId, @RequestBody @Valid ParticipantDtos.CreateParticipantReq req) {
         var res = participantService.add(voteId, req.displayName());
         return ResponseEntity.ok(res);
     }
 
-
+    @Operation(
+            summary = "참여자 삭제",
+            description = "특정 참여자를 삭제합니다."
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "204", description = "참여자 삭제 성공", content = @Content),
+            @ApiResponse(responseCode = "404", description = "참여자를 찾을 수 없음", content = @Content)
+    })
     @DeleteMapping("/participants/{participantId}")
     public ResponseEntity<Void> remove(@PathVariable Long participantId) {
         participantService.remove(participantId);

src/main/java/com/workingdead/meet/controller/ParticipantController.java

@@ -4,44 +4,81 @@
 import com.workingdead.meet.entity.*;
 import com.workingdead.meet.repository.*;
 import com.workingdead.meet.service.*;
+import io.swagger.v3.oas.annotations.*;
+import io.swagger.v3.oas.annotations.media.*;
+import io.swagger.v3.oas.annotations.responses.*;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 import java.util.List;
 
-
+@Tag(name = "Vote", description = "투표 관리 API")
 @RestController
 @RequestMapping("/votes")
 public class VoteController {
     private final VoteService voteService;
     public VoteController(VoteService voteService) { this.voteService = voteService; }
 
-
+    @Operation(
+            summary = "투표 목록 조회",
+            description = "모든 투표 목록을 조회합니다. 각 투표의 기본 정보(id, name, code, adminUrl, shareUrl, startDate, endDate)를 반환합니다." +
+                    "code+baseUrl=shareUrl"
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "조회 성공",
+                    content = @Content(schema = @Schema(implementation = VoteDtos.VoteSummary.class)))
+    })
     // 0.1 홈화면 리스트 & 생성
     @GetMapping
     public List<VoteDtos.VoteSummary> list() { return voteService.listAll(); }
 
+    // 0.2 투표 설정 화면 읽기/수정/삭제
+    @GetMapping("/{id}")
+    public VoteDtos.VoteDetail get(@PathVariable Long id) { return voteService.get(id); }
+
 
+    @Operation(
+            summary = "새 투표 생성",
+            description = "새로운 투표를 생성합니다. 고유한 code가 자동 생성되며, shareUrl을 통해 참여자에게 공유할 수 있습니다."
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "생성 성공",
+                    content = @Content(schema = @Schema(implementation = VoteDtos.VoteSummary.class))),
+            @ApiResponse(responseCode = "400", description = "잘못된 요청 (name이 비어있는 경우)", content = @Content)
+    })
     @PostMapping
     public ResponseEntity<VoteDtos.VoteSummary> create(@RequestBody @Valid VoteDtos.CreateVoteReq req) {
-        var res = voteService.create(req.name());
+        var res = voteService.create(req);
 // 0.2.3 링크 복사: res.shareUrl 포함
         return ResponseEntity.ok(res);
     }
 
 
-    // 0.2 투표 설정 화면 읽기/수정/삭제
-    @GetMapping("/{id}")
-    public VoteDtos.VoteDetail get(@PathVariable Long id) { return voteService.get(id); }
-
-
+    @Operation(
+            summary = "투표 정보 수정",
+            description = "투표의 이름 또는 날짜 범위를 수정합니다. endDate는 startDate보다 크거나 같아야 합니다."
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "200", description = "수정 성공",
+                    content = @Content(schema = @Schema(implementation = VoteDtos.VoteDetail.class))),
+            @ApiResponse(responseCode = "400", description = "잘못된 요청 (endDate < startDate)", content = @Content),
+            @ApiResponse(responseCode = "404", description = "투표를 찾을 수 없음", content = @Content)
+    })
     @PatchMapping("/{id}")
     public VoteDtos.VoteDetail update(@PathVariable Long id, @RequestBody VoteDtos.UpdateVoteReq req) {
 // 날짜 범위 검증은 서비스에서 처리 (end >= start)
         return voteService.update(id, req);
     }
 
-
+    @Operation(
+            summary = "투표 삭제",
+            description = "투표를 삭제합니다. 연관된 모든 참여자도 함께 삭제됩니다 (cascade)."
+    )
+    @ApiResponses({
+            @ApiResponse(responseCode = "204", description = "삭제 성공", content = @Content),
+            @ApiResponse(responseCode = "404", description = "투표를 찾을 수 없음", content = @Content)
+    })
     @DeleteMapping("/{id}")
     public ResponseEntity<Void> delete(@PathVariable Long id) {
         voteService.delete(id);

src/main/java/com/workingdead/meet/controller/VoteController.java

@@ -6,7 +6,12 @@
 
 
 public class VoteDtos {
-    public record CreateVoteReq(@NotBlank String name) {}
+    public record CreateVoteReq(
+            @NotBlank String name,
+            LocalDate startDate,
+            LocalDate endDate,
+            List<String> participantNames  // 참여자 이름 리스트 (optional)
+    ) {}
     public record UpdateVoteReq(String name, LocalDate startDate, LocalDate endDate) {}
 
     public record VoteSummary(Long id, String name, String code, String adminUrl, String shareUrl, LocalDate startDate, LocalDate endDate) {}

src/main/java/com/workingdead/meet/dto/VoteDtos.java

@@ -2,6 +2,7 @@
 
 import com.workingdead.meet.dto.ParticipantDtos;
 import com.workingdead.meet.dto.VoteDtos;
+import com.workingdead.meet.entity.Participant;
 import com.workingdead.meet.entity.Vote;
 import com.workingdead.meet.repository.VoteRepository;
 import jakarta.transaction.Transactional;
@@ -26,9 +27,29 @@ public VoteService(VoteRepository voteRepo, @Value("${app.base-url:http://localh
     }
 
 
-    public VoteDtos.VoteSummary create(String name) {
+    public VoteDtos.VoteSummary create(VoteDtos.CreateVoteReq req) {
+        //1. Vote c
         String code = genCode(8);
-        Vote v = new Vote(name, code);
+        Vote v = new Vote(req.name(), code);
+
+        // 2. 날짜 범위 설정 (있으면)
+        if (req.startDate() != null && req.endDate() != null) {
+            if (req.endDate().isBefore(req.startDate())) {
+                throw new IllegalArgumentException("endDate must be >= startDate");
+            }
+            v.setDateRange(req.startDate(), req.endDate());
+
+            // 3. 참여자 추가 (있으면)
+            if (req.participantNames() != null && !req.participantNames().isEmpty()) {
+                for (String name : req.participantNames()) {
+                    if (name != null && !name.isBlank()) {
+                        Participant p = new Participant(v, name.trim());
+                        v.getParticipants().add(p);
+                    }
+                }
+            }
+        }
+
         voteRepo.save(v);
         return toSummary(v);
     }

src/main/java/com/workingdead/meet/service/VoteService.java

@@ -56,3 +56,11 @@ spring:
       init:
         mode: always                # 외부 DB에서도 init 실행
         platform: postgresql        # schema-@@platform@@.sql 매핑용
+
+springdoc:
+  api-docs:
+    path: /v3/api-docs
+  swagger-ui:
+    path: /swagger-ui.html
+    enabled: true
+  packages-to-scan: com.workingdead