[feat/docs] Config 서버 API 연동 (우분투 계정 삭제) 및 API 명세서 작성

src/main/java/DGU_AI_LAB/admin_be/domain/alarm/controller/docs/AlarmApi.java

@@ -13,7 +13,7 @@
 import jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
 
-@Tag(name = "Slack 및 E-mail", description = "Slack 및 Email 알림 API")
+@Tag(name = "0. Slack 및 E-mail", description = "Slack 및 Email 알림 API")
 public interface AlarmApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/containerImage/controller/docs/ContainerImageApi.java

@@ -15,10 +15,10 @@
 
 import java.util.List;
 
-@Tag(name = "이미지 관리", description = "컨테이너 이미지 생성 및 조회 API")
+@Tag(name = "2. 이미지 관리", description = "컨테이너 이미지 조회 API")
 public interface ContainerImageApi {
 
-    @Operation(summary = "이미지 생성", description = "새로운 컨테이너 이미지를 등록합니다.")
+    @Operation(summary = "이미지 생성", description = "새로운 컨테이너 이미지를 등록합니다. -> 관리자용으로 만들어졌으니, 수정 필요합니다. ")
     @ApiResponse(responseCode = "200", description = "이미지 생성 성공",
             content = @Content(schema = @Schema(implementation = ContainerImageResponseDTO.class)))
     ResponseEntity<ContainerImageResponseDTO> createImage(

src/main/java/DGU_AI_LAB/admin_be/domain/dashboard/controller/docs/DashBoardApi.java

@@ -18,7 +18,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 
 
-@Tag(name = "사용자 대시보드 API", description = "대시보드용 API")
+@Tag(name = "2. 사용자 대시보드 API", description = "대시보드용 API")
 @RequestMapping("/api/dashboard")
 public interface DashBoardApi {
 

src/main/java/DGU_AI_LAB/admin_be/domain/groups/controller/GroupController.java

@@ -1,5 +1,6 @@
 package DGU_AI_LAB.admin_be.domain.groups.controller;
 
+import DGU_AI_LAB.admin_be.domain.groups.controller.docs.GroupApi;
 import DGU_AI_LAB.admin_be.domain.groups.dto.request.CreateGroupRequestDTO;
 import DGU_AI_LAB.admin_be.domain.groups.dto.response.GroupResponseDTO;
 import DGU_AI_LAB.admin_be.domain.groups.service.GroupService;
@@ -16,7 +17,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/groups")
-public class GroupController {
+public class GroupController implements GroupApi {
 
     private final GroupService groupService;
 

src/main/java/DGU_AI_LAB/admin_be/domain/groups/controller/docs/GroupApi.java

@@ -0,0 +1,32 @@
+package DGU_AI_LAB.admin_be.domain.groups.controller.docs;
+
+import DGU_AI_LAB.admin_be.domain.groups.dto.request.CreateGroupRequestDTO;
+import DGU_AI_LAB.admin_be.global.common.SuccessResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+@Tag(name = "2. 그룹 API", description = "사용자용 그룹 목록 조회, 그룹 생성 API")
+public interface GroupApi {
+
+    @Operation(summary = "모든 그룹 목록 조회", description = "시스템에 등록된 모든 그룹의 정보를 조회합니다. 사용 신청 단계에서 이 목록을 조회하고, 그룹을 선택할 수 있습니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "조회된 그룹 정보 없음")
+    })
+    @GetMapping
+    ResponseEntity<SuccessResponse<?>> getGroups();
+
+    @Operation(summary = "새로운 그룹 생성", description = "새로운 그룹을 생성하고 DB에 저장합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "201", description = "생성 성공"),
+            @ApiResponse(responseCode = "400", description = "잘못된 요청 (필수 필드 누락 등)"),
+            @ApiResponse(responseCode = "409", description = "중복된 GID를 가진 그룹이 이미 존재함")
+    })
+    @PostMapping
+    ResponseEntity<SuccessResponse<?>> createGroup(@RequestBody @Valid CreateGroupRequestDTO dto);
+}

src/main/java/DGU_AI_LAB/admin_be/domain/groups/dto/request/CreateGroupRequestDTO.java

@@ -1,15 +1,19 @@
 package DGU_AI_LAB.admin_be.domain.groups.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Positive;
 import lombok.Builder;
 
+@Schema(description = "1. 그룹 생성 요청 DTO")
 @Builder
 public record CreateGroupRequestDTO(
+        @Schema(description = "할당할 우분투 GID (Group ID)", example = "1001")
         @NotNull @Positive
         Long ubuntuGid,
 
+        @Schema(description = "생성할 그룹명", example = "developers")
         @NotBlank
         String groupName
 ) {

src/main/java/DGU_AI_LAB/admin_be/domain/pod/controller/docs/PodApi.java

@@ -10,7 +10,7 @@
 
 import java.util.List;
 
-@Tag(name = "Kubernetes Pods", description = "쿠버네티스 Pod 조회 API")
+@Tag(name = "0. Kubernetes Pods", description = "쿠버네티스 Pod 조회 API")
 public interface PodApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/AdminRequestController.java

@@ -1,5 +1,6 @@
 package DGU_AI_LAB.admin_be.domain.requests.controller;
 
+import DGU_AI_LAB.admin_be.domain.requests.controller.docs.AdminRequestApi;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveModificationDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveRequestDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.RejectRequestDTO;
@@ -20,7 +21,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/admin/requests")
-public class AdminRequestController {
+public class AdminRequestController implements AdminRequestApi {
 
     private final AdminRequestCommandService adminRequestCommandService;
     private final AdminRequestQueryService adminRequestQueryService;

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/ConfigRequestController.java

@@ -1,5 +1,6 @@
 package DGU_AI_LAB.admin_be.domain.requests.controller;
 
+import DGU_AI_LAB.admin_be.domain.requests.controller.docs.ConfigRequestApi;
 import DGU_AI_LAB.admin_be.domain.requests.dto.response.AcceptInfoResponseDTO;
 import DGU_AI_LAB.admin_be.domain.requests.service.ConfigRequestService;
 import lombok.RequiredArgsConstructor;
@@ -9,7 +10,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/requests/config")
-public class ConfigRequestController {
+public class ConfigRequestController implements ConfigRequestApi {
 
     private final ConfigRequestService configRequestService;
 

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/AcceptInfoApi.java

@@ -9,7 +9,7 @@
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.ResponseEntity;
 
-@Tag(name = "Config Server용 승인 정보 관리", description = "Ubuntu username별 승인 정보 조회 API")
+@Tag(name = "0. Config Server용 승인 정보 관리", description = "Ubuntu username별 승인 정보 조회 API")
 public interface AcceptInfoApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/AdminRequestApi.java

@@ -1,58 +1,74 @@
 package DGU_AI_LAB.admin_be.domain.requests.controller.docs;
 
+import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveModificationDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.ApproveRequestDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.request.RejectRequestDTO;
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.ChangeRequestResponseDTO;
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.ContainerInfoDTO;
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.ResourceUsageDTO;
 import DGU_AI_LAB.admin_be.domain.requests.dto.response.SaveRequestResponseDTO;
 import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.media.ArraySchema;
-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.validation.Valid;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 
-@Tag(name = "관리자용 서버 사용 신청 관리", description = "관리자용 서버 사용 신청 관리 API")
+@Tag(name = "1. 관리자 서버 사용 신청 처리", description = "관리자용 서버 사용 신청 관리 API")
 public interface AdminRequestApi {
 
-    @Operation(
-            summary = "모든 신청 목록 조회",
-            description = "상태에 상관없이 모든 사용 신청을 조회합니다."
-    )
-    @ApiResponse(
-            responseCode = "200", description = "조회 성공",
-            content = @Content(array = @ArraySchema(schema = @Schema(implementation = SaveRequestResponseDTO.class)))
-    )
+    @Operation(summary = "변경 요청 승인", description = "사용자의 변경 요청을 승인합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "변경 요청을 찾을 수 없음"),
+            @ApiResponse(responseCode = "409", description = "요청 상태가 PENDING이 아님")
+    })
+    @PatchMapping("/change/approve")
+    ResponseEntity<Void> approveModification(
+            @AuthenticationPrincipal(expression = "userId") Long adminId,
+            @RequestBody @Valid ApproveModificationDTO dto
+    );
+
+    @Operation(summary = "모든 리소스 사용량 조회", description = "현재 사용 중인 컨테이너들의 리소스 사용량을 조회합니다.")
+    @GetMapping("/usage")
+    ResponseEntity<List<ResourceUsageDTO>> getAllResourceUsage();
+
+    @Operation(summary = "모든 컨테이너 정보 조회", description = "현재 활성화된 모든 컨테이너의 상세 정보를 조회합니다.")
+    @GetMapping("/containers")
+    ResponseEntity<List<ContainerInfoDTO>> getAllActiveContainers();
+
+    @Operation(summary = "모든 요청 목록 조회", description = "모든 상태의 사용자 요청 목록을 조회합니다.")
+    @GetMapping
     ResponseEntity<List<SaveRequestResponseDTO>> getAllRequests();
 
-    @Operation(
-            summary = "신청 승인",
-            description = "해당 신청의 상태를 FULFILLED로 변경하고 approvedAt을 현재 시각으로 설정합니다. expiresAt, volumeSizeGiB, imageId, rsgroupId를 갱신합니다."
-    )
-    @ApiResponse(
-            responseCode = "200", description = "승인 성공",
-            content = @Content(schema = @Schema(implementation = SaveRequestResponseDTO.class))
-    )
-    ResponseEntity<SaveRequestResponseDTO> approve(
-            @io.swagger.v3.oas.annotations.parameters.RequestBody(
-                    description = "승인 DTO", required = true
-            )
-            ApproveRequestDTO dto
-    );
+    @Operation(summary = "신규 신청 목록 조회", description = "PENDING 상태의 신규 사용자 신청 목록을 조회합니다.")
+    @GetMapping("/new")
+    ResponseEntity<List<SaveRequestResponseDTO>> getNewRequests();
 
-    @Operation(
-            summary = "신청 거절",
-            description = "해당 신청의 상태를 DENIED로 변경하고 관리 코멘트를 기록합니다."
-    )
-    @ApiResponse(
-            responseCode = "200", description = "거절 성공",
-            content = @Content(schema = @Schema(implementation = SaveRequestResponseDTO.class))
-    )
-    ResponseEntity<SaveRequestResponseDTO> reject(
-            @io.swagger.v3.oas.annotations.parameters.RequestBody(
-                    description = "거절 DTO", required = true
-            )
-            RejectRequestDTO dto
-    );
+    @Operation(summary = "변경 요청 목록 조회", description = "PENDING 상태의 사용자 변경 요청 목록을 조회합니다.")
+    @GetMapping("/change")
+    ResponseEntity<List<ChangeRequestResponseDTO>> getChangeRequests();
+
+    @Operation(summary = "신규 신청 승인", description = "신규 사용자 신청을 승인하고, 계정 및 리소스를 할당합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "요청을 찾을 수 없음"),
+            @ApiResponse(responseCode = "409", description = "요청 상태가 PENDING이 아님"),
+            @ApiResponse(responseCode = "502", description = "외부 서버 오류")
+    })
+    @PatchMapping("/approval")
+    ResponseEntity<SaveRequestResponseDTO> approve(@RequestBody @Valid ApproveRequestDTO dto);
+
+    @Operation(summary = "신규 신청 거절", description = "신규 사용자 신청을 거절합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "요청을 찾을 수 없음"),
+            @ApiResponse(responseCode = "409", description = "요청 상태가 PENDING 또는 FULFILLED가 아님")
+    })
+    @PatchMapping("/reject")
+    ResponseEntity<SaveRequestResponseDTO> reject(@RequestBody @Valid RejectRequestDTO dto);
 }

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/ConfigRequestApi.java

@@ -0,0 +1,51 @@
+package DGU_AI_LAB.admin_be.domain.requests.controller.docs;
+
+import DGU_AI_LAB.admin_be.domain.requests.dto.response.AcceptInfoResponseDTO;
+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.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+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.RequestParam;
+
+@Tag(name = "0. Config Server용 API", description = "내부 Config Server 연동을 위한 API")
+@RequestMapping("/api/requests/config")
+public interface ConfigRequestApi {
+
+    @Operation(summary = "우분투 계정명 사용 가능 여부 확인", description = "지정된 우분투 계정명이 사용 가능한지 확인합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공",
+                    content = @io.swagger.v3.oas.annotations.media.Content(
+                            mediaType = "application/json",
+                            examples = {
+                                    @io.swagger.v3.oas.annotations.media.ExampleObject(
+                                            name = "사용 가능",
+                                            value = "{\"available\": true}"
+                                    ),
+                                    @io.swagger.v3.oas.annotations.media.ExampleObject(
+                                            name = "사용 불가능",
+                                            value = "{\"available\": false}"
+                                    )
+                            }
+                    )
+            )
+    })
+    @GetMapping("/check-username")
+    ResponseEntity<?> checkUbuntuUsername(
+            @RequestParam @Parameter(description = "확인할 우분투 계정명", example = "toni") String username
+    );
+
+    @Operation(summary = "요청 승인 정보 조회", description = "지정된 우분투 계정명에 대한 승인된 요청 정보를 조회합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "성공"),
+            @ApiResponse(responseCode = "404", description = "승인된 요청을 찾을 수 없음")
+    })
+    @GetMapping("/{username}")
+    ResponseEntity<AcceptInfoResponseDTO> getAcceptInfo(
+            @PathVariable @Parameter(description = "승인 정보 조회 대상 계정명", example = "toni") String username
+    );
+}

src/main/java/DGU_AI_LAB/admin_be/domain/requests/controller/docs/RequestApi.java

@@ -16,7 +16,7 @@
 
 import java.util.List;
 
-@Tag(name = "서버 사용 신청", description = "서버 사용 신청 API")
+@Tag(name = "2. 서버 사용 신청", description = "서버 사용 신청 API")
 public interface RequestApi {
 
     @Operation(

src/main/java/DGU_AI_LAB/admin_be/domain/requests/dto/request/ApproveRequestDTO.java

@@ -1,12 +1,33 @@
 package DGU_AI_LAB.admin_be.domain.requests.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+
 import java.time.LocalDateTime;
 
+@Schema(description = "관리자용 요청 승인 요청 DTO")
 public record ApproveRequestDTO(
+
+        @Schema(description = "승인할 요청 ID", example = "1")
+        @NotNull(message = "요청 ID는 필수로 입력해야 합니다.")
         Long requestId,
+
+        @Schema(description = "적용할 컨테이너 이미지 ID", example = "1")
+        @NotNull(message = "이미지 ID는 필수로 입력해야 합니다.")
         Long imageId,
+
+        @Schema(description = "할당할 리소스 그룹 ID", example = "1")
+        @NotNull(message = "리소스 그룹 ID는 필수로 입력해야 합니다.")
         Integer resourceGroupId,
+
+        @Schema(description = "할당할 볼륨 크기 (GiB)", example = "20")
+        @NotNull(message = "볼륨 크기는 필수로 입력해야 합니다.")
         Long volumeSizeGiB,
+
+        @Schema(description = "만료일", example = "2025-12-31T23:59:59")
+        @NotNull(message = "만료일은 필수로 입력해야 합니다.")
         LocalDateTime expiresAt,
+
+        @Schema(description = "관리자 승인 코멘트 (선택 사항)", example = "사용 목적에 따라 리소스를 할당함")
         String adminComment
 ) {}

src/main/java/DGU_AI_LAB/admin_be/domain/requests/dto/request/RejectRequestDTO.java

@@ -1,6 +1,17 @@
 package DGU_AI_LAB.admin_be.domain.requests.dto.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+
+@Schema(description = "1. 관리자용 요청 거절 요청 DTO")
 public record RejectRequestDTO(
+
+        @Schema(description = "거절할 요청 ID", example = "3")
+        @NotNull(message = "요청 ID는 필수로 입력해야 합니다.")
         Long requestId,
+
+        @Schema(description = "관리자 거절 코멘트", example = "신청서 양식에 맞지 않아 거절합니다.")
+        @NotBlank(message = "거절 사유를 필수로 입력해야 합니다.")
         String adminComment
 ) {}

src/main/java/DGU_AI_LAB/admin_be/domain/requests/dto/response/AcceptInfoResponseDTO.java

@@ -8,6 +8,7 @@
 
 @Builder
 public record AcceptInfoResponseDTO(
+
         String username,
         String image,
         Long uid,