Skip to content

Commit 731be89

Browse files
doup2001doup2001
authored
Merge pull request #19 from GDGoC-Gachon/feat-swagger
Feat : swagger @tag 기능 추가
2 parents 491e2cd + 5e37a62 commit 731be89

File tree

6 files changed

+146
-34
lines changed

6 files changed

+146
-34
lines changed

‎src/main/java/com/gdg/homepage/landing/admin/controller/AdminApi.java‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
import com.gdg.homepage.landing.admin.service.AdminServiceImpl;
1010
import com.gdg.homepage.landing.admin.service.MemberAdminServiceImpl;
1111
import com.gdg.homepage.landing.register.service.RegisterService;
12+
import io.swagger.v3.oas.annotations.Operation;
13+
import io.swagger.v3.oas.annotations.tags.Tag;
1214
import lombok.RequiredArgsConstructor;
1315
import org.springframework.web.bind.annotation.*;
1416

@@ -17,45 +19,57 @@
1719
@RestController
1820
@RequestMapping("/admin")
1921
@RequiredArgsConstructor
22+
@Tag(name = "Admin API", description = "관리자 관련 API")
2023
public class AdminApi {
2124

2225
private final AdminServiceImpl adminService;
23-
private final MemberAdminServiceImpl memberAdminService;
24-
private final RegisterService registerService;
2526

26-
// 가입 일정 생성
27+
@Operation(
28+
summary = "가입 일정 생성",
29+
description = "리크루팅에 대한 새로운 가입 일정을 생성합니다."
30+
)
2731
@PostMapping("/joinPeriod/create")
28-
public ApiResponse<String> createJoinPeriod(@RequestBody JoinPeriodRequest JoinPeriodRequest) {
32+
public ApiResponse<String> createJoinPeriod(@RequestBody JoinPeriodRequest joinPeriodRequest) {
2933
try {
30-
adminService.createJoinPeriod(JoinPeriodRequest);
34+
adminService.createJoinPeriod(joinPeriodRequest);
3135
return ApiResponse.created("JoinPeriod is created.");
3236
} catch (Exception e) {
3337
throw new CustomException(ErrorCode.INTERNAL_SERVER_ERROR);
3438
}
3539
}
3640

37-
// 가입 일정 수정
41+
@Operation(
42+
summary = "가입 일정 수정",
43+
description = "특정 ID의 가입 일정을 수정합니다."
44+
)
3845
@PutMapping("/joinPeriod/update/{id}")
39-
public ApiResponse<JoinPeriodResponse> updateJoinPeriod(@PathVariable("id") Long id, @RequestBody JoinPeriodRequest JoinPeriodRequest) {
46+
public ApiResponse<JoinPeriodResponse> updateJoinPeriod(@PathVariable("id") Long id, @RequestBody JoinPeriodRequest joinPeriodRequest) {
4047
try {
41-
JoinPeriodResponse JoinPeriodResponseDto = adminService.updateJoinPeriod(id, JoinPeriodRequest);
42-
return ApiResponse.ok(JoinPeriodResponseDto);
48+
JoinPeriodResponse responseDto = adminService.updateJoinPeriod(id, joinPeriodRequest);
49+
return ApiResponse.ok(responseDto);
4350
} catch (Exception e) {
4451
throw new CustomException(ErrorCode.INTERNAL_SERVER_ERROR);
4552
}
4653
}
47-
// 가입 목록 조회
54+
55+
@Operation(
56+
summary = "가입 목록 조회",
57+
description = "리크루팅 모든 가입 일정을 조회합니다."
58+
)
4859
@GetMapping("/joinPeriod/all")
4960
public ApiResponse<List<JoinPeriodResponse>> getAllJoinPeriods() {
5061
try {
51-
List<JoinPeriodResponse> JoinPeriodResponseDtos = adminService.getAllJoinPeriods();
52-
return ApiResponse.ok(JoinPeriodResponseDtos);
62+
List<JoinPeriodResponse> responseDtos = adminService.getAllJoinPeriods();
63+
return ApiResponse.ok(responseDtos);
5364
} catch (Exception e) {
5465
throw new CustomException(ErrorCode.INTERNAL_SERVER_ERROR);
5566
}
5667
}
5768

58-
// 가입 조기 종료
69+
@Operation(
70+
summary = "가입 조기 종료",
71+
description = "리크루팅 특정 가입 일정을 조기 종료합니다."
72+
)
5973
@DeleteMapping("/joinPeriod/terminate/{id}")
6074
public ApiResponse<String> terminateJoinPeriod(@PathVariable("id") Long id) {
6175
try {
@@ -66,6 +80,11 @@ public ApiResponse<String> terminateJoinPeriod(@PathVariable("id") Long id) {
6680
}
6781
}
6882

83+
@Operation(
84+
summary = "분석 페이지 데이터 조회",
85+
description = "회원 총수, 현재 등록자 수, 페이지 조회 수 등의 분석 데이터를 조회합니다."
86+
)
87+
6988
// 분석 대시보드 조회
7089
@GetMapping("/analytic")
7190
public ApiResponse<AnalyticsResponse> getStatistics() {

‎src/main/java/com/gdg/homepage/landing/admin/controller/MemberAdminApi.java‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
import com.gdg.homepage.landing.admin.dto.MemberUpgradeRequest;
1010
import com.gdg.homepage.landing.admin.service.MemberAdminService;
1111
import com.gdg.homepage.landing.member.dto.CustomUserDetails;
12+
import io.swagger.v3.oas.annotations.Operation;
13+
import io.swagger.v3.oas.annotations.tags.Tag;
1214
import jakarta.validation.Valid;
1315
import lombok.RequiredArgsConstructor;
1416
import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -17,42 +19,60 @@
1719
@RestController
1820
@RequestMapping("/admin/v1/member")
1921
@RequiredArgsConstructor
22+
@Tag(
23+
name = "Member Admin API",
24+
description = "관리자용 멤버 관리 API"
25+
)
2026
public class MemberAdminApi {
2127

2228
private final MemberAdminService adminService;
2329

24-
25-
// 승인된 멤버 가져오기
30+
@Operation(
31+
summary = "승인된 멤버 목록 조회",
32+
description = "승인된 멤버들의 페이징 처리된 목록을 반환합니다."
33+
)
2634
@GetMapping("/list")
2735
public ApiResponse<PageResponse<MemberListResponse>> getMemberList(PageRequest pageRequest) {
2836
return ApiResponse.ok(adminService.findAll(pageRequest));
2937
}
3038

31-
// 멤버 상세 조회하기
39+
@Operation(
40+
summary = "멤버 상세 조회",
41+
description = "멤버 ID로 멤버의 상세 정보를 조회합니다."
42+
)
3243
@GetMapping("/{id}")
3344
public ApiResponse<MemberDetailResponse> getMemberDetail(@PathVariable("id") Long id) {
3445
return ApiResponse.ok(adminService.loadMember(id));
3546
}
3647

37-
// 미승인된 멤버 가져오기
48+
@Operation(
49+
summary = "미승인된 멤버 목록 조회",
50+
description = "승인되지 않은 멤버들의 페이징 처리된 목록을 반환합니다."
51+
)
3852
@GetMapping("/list/not")
3953
public ApiResponse<PageResponse<MemberListResponse>> getMemberListNotApproved(PageRequest pageRequest) {
4054
return ApiResponse.ok(adminService.findAllNotApproved(pageRequest));
4155
}
4256

43-
// 멤버 승인하기
57+
@Operation(
58+
summary = "멤버 승인",
59+
description = "관리자가 멤버를 승인합니다."
60+
)
4461
@PutMapping("/approve")
4562
public ApiResponse<String> approveRole(@AuthenticationPrincipal CustomUserDetails memberDetails, @RequestBody @Valid MemberApproveRequest request){
4663
request.setAdminId(memberDetails.getId());
4764
adminService.approveMember(request);
4865
return ApiResponse.created("승인 되었습니다.");
4966
}
5067

51-
// 멤버 권한 수정하기
68+
@Operation(
69+
summary = "멤버 권한 수정",
70+
description = "관리자가 멤버의 권한을 수정합니다."
71+
)
5272
@PutMapping()
5373
public ApiResponse<String> changeRole(@AuthenticationPrincipal CustomUserDetails memberDetails, @RequestBody @Valid MemberUpgradeRequest request) {
5474
request.setAdminId(memberDetails.getId());
5575
adminService.changeRole(request);
5676
return ApiResponse.ok("권한 수정 성공되었습니다.");
5777
}
58-
}
78+
}

‎src/main/java/com/gdg/homepage/landing/admin/controller/ViewApi.java‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,29 @@
22

33
import com.gdg.homepage.common.response.ApiResponse;
44
import com.gdg.homepage.landing.admin.service.AdminServiceImpl;
5+
import io.swagger.v3.oas.annotations.Operation;
6+
import io.swagger.v3.oas.annotations.tags.Tag;
57
import lombok.RequiredArgsConstructor;
68
import org.springframework.web.bind.annotation.PostMapping;
79
import org.springframework.web.bind.annotation.RestController;
810

911
@RestController
1012
@RequiredArgsConstructor
13+
@Tag(
14+
name = "View API", description = "관리자 화면 제공 API")
1115
public class ViewApi {
1216

1317
private final AdminServiceImpl adminService;
1418

1519
// 페이지 조회 수 증가
20+
@Operation(
21+
summary = "페이지 조회 수 증가",
22+
description = "해당 API를 호출하면 특정 페이지의 조회 수가 1 증가합니다."
23+
)
1624
@PostMapping("/pageView/increment")
1725
public ApiResponse<String> incrementPageViewCount() {
1826
adminService.incrementPageView();
1927
return ApiResponse.ok("조회수 증가");
2028
}
21-
29+
2230
}
23-

‎src/main/java/com/gdg/homepage/landing/faq/controller/FAQApi.java‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,28 @@
66
import com.gdg.homepage.landing.faq.dto.FAQRequest;
77
import com.gdg.homepage.landing.faq.dto.FAQResponse;
88
import com.gdg.homepage.landing.faq.service.FAQServiceImpl;
9+
import io.swagger.v3.oas.annotations.Operation;
10+
import io.swagger.v3.oas.annotations.tags.Tag;
911
import lombok.RequiredArgsConstructor;
1012
import org.springframework.web.bind.annotation.*;
1113

1214
import java.util.List;
1315

16+
@Tag(
17+
name = "FAQ 관리 API",
18+
description = "관리자용 FAQ 생성, 수정, 삭제 및 조회 기능"
19+
)
1420
@RestController
1521
@RequestMapping("/admin/faq")
1622
@RequiredArgsConstructor
1723
public class FAQApi {
1824

1925
private final FAQServiceImpl FAQService;
2026

21-
// FAQ 추가
27+
@Operation(
28+
summary = "FAQ 생성",
29+
description = "새로운 FAQ 항목을 생성합니다."
30+
)
2231
@PostMapping("/create")
2332
public ApiResponse<FAQResponse> createFAQ(@RequestBody FAQRequest faqRequest) {
2433
try {
@@ -29,7 +38,10 @@ public ApiResponse<FAQResponse> createFAQ(@RequestBody FAQRequest faqRequest) {
2938
}
3039
}
3140

32-
// FAQ 수정
41+
@Operation(
42+
summary = "FAQ 수정",
43+
description = "기존 FAQ 항목을 ID를 기반으로 수정합니다."
44+
)
3345
@PutMapping("/update/{id}")
3446
public ApiResponse<FAQResponse> updateFAQ(@PathVariable("id") Long id, @RequestBody FAQRequest faqRequest) {
3547
try {
@@ -40,7 +52,10 @@ public ApiResponse<FAQResponse> updateFAQ(@PathVariable("id") Long id, @RequestB
4052
}
4153
}
4254

43-
// FAQ 삭제
55+
@Operation(
56+
summary = "FAQ 삭제",
57+
description = "FAQ 항목을 ID를 기반으로 삭제합니다."
58+
)
4459
@DeleteMapping("/delete/{id}")
4560
public ApiResponse<String> deleteFAQ(@PathVariable("id") Long id) {
4661
try {
@@ -51,7 +66,10 @@ public ApiResponse<String> deleteFAQ(@PathVariable("id") Long id) {
5166
}
5267
}
5368

54-
// FAQ 목록 조회
69+
@Operation(
70+
summary = "FAQ 전체 조회",
71+
description = "모든 FAQ 항목을 조회합니다."
72+
)
5573
@GetMapping("/all")
5674
public ApiResponse<List<FAQResponse>> getAllFAQs() {
5775
try {
@@ -61,4 +79,4 @@ public ApiResponse<List<FAQResponse>> getAllFAQs() {
6179
throw new CustomException(ErrorCode.INTERNAL_SERVER_ERROR);
6280
}
6381
}
64-
}
82+
}

‎src/main/java/com/gdg/homepage/landing/member/controller/MemberApi.java‎

Lines changed: 43 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,73 +9,110 @@
99
import lombok.RequiredArgsConstructor;
1010
import org.springframework.security.core.annotation.AuthenticationPrincipal;
1111
import org.springframework.web.bind.annotation.*;
12+
import io.swagger.v3.oas.annotations.Operation;
13+
import io.swagger.v3.oas.annotations.tags.Tag;
1214

1315
@RestController
1416
@RequestMapping("/api/v1/member")
1517
@RequiredArgsConstructor
18+
@Tag(
19+
name = "Member",
20+
description = "멤버 관련 API"
21+
)
1622
public class MemberApi {
1723

1824
private final MemberService memberService;
1925
private final EmailService emailService;
2026

21-
// 이메일 전송하기
2227
@PostMapping("/email")
28+
@Operation(
29+
summary = "이메일 전송",
30+
description = "이메일 인증을 위해 메일을 전송합니다."
31+
)
2332
public ApiResponse<String> email(@RequestBody EmailSendRequest request) throws MessagingException {
2433
emailService.sendEmail(request.getEmail());
2534
return ApiResponse.created("성공적으로 메일이 전송되었습니다.");
2635
}
2736

28-
// 이메일 검증하기
2937
@PostMapping("/email/verify")
38+
@Operation(
39+
summary = "이메일 인증번호 검증",
40+
description = "이메일 인증번호를 검증합니다."
41+
)
3042
public ApiResponse<String> verify(@RequestBody EmailVerifyRequest request) {
3143
if (!emailService.verifyCode(request.getEmail(), request.getCode())){
3244
throw new NotVerifiedException("인증번호가 틀렸습니다.");
3345
}
34-
3546
return ApiResponse.created("메일이 인증되었습니다.");
3647
}
3748

3849
@PostMapping("/register")
50+
@Operation(
51+
summary = "회원 가입",
52+
description = "GDG Gachon 멤버의 회원 가입을 처리합니다."
53+
)
3954
public ApiResponse<String> create(@RequestBody MemberRegisterWrapper wrapper) {
4055
memberService.registerMember(wrapper.getMember(), wrapper.getApply());
4156
return ApiResponse.created("성공적으로 제출되었습니다.");
4257
}
4358

4459
@PostMapping("/login")
60+
@Operation(
61+
summary = "로그인",
62+
description = "로그인을 처리합니다."
63+
)
4564
public ApiResponse<MemberLoginResponse> login(@RequestBody MemberLoginRequest request) {
4665
return ApiResponse.ok(memberService.login(request));
4766
}
4867

4968
@PostMapping("/logout")
69+
@Operation(
70+
summary = "로그아웃",
71+
description = "로그아웃을 처리합니다."
72+
)
5073
public ApiResponse<String> logout() {
5174
memberService.logout();
5275
return ApiResponse.ok("성공적으로 로그아웃 되었습니다.");
5376
}
5477

5578
@GetMapping("/myPage")
79+
@Operation(
80+
summary = "마이페이지 조회",
81+
description = "마이페이지 정보를 조회합니다."
82+
)
5683
public ApiResponse<MemberDetailResponse> myPage(@AuthenticationPrincipal CustomUserDetails memberDetails) {
57-
5884
return ApiResponse.ok(memberService.loadMyMember(memberDetails.getId()));
5985
}
6086

6187
@DeleteMapping()
88+
@Operation(
89+
summary = "회원 탈퇴",
90+
description = "회원 탈퇴를 처리합니다."
91+
)
6292
public ApiResponse<String> delete(@AuthenticationPrincipal CustomUserDetails memberDetails) {
6393
memberService.deleteMember(memberDetails.getId());
6494
return ApiResponse.ok("성공적으로 탈퇴되었습니다.");
6595
}
6696

6797
@PostMapping("/request")
98+
@Operation(
99+
summary = "비밀번호 재설정 요청",
100+
description = "비밀번호 재설정을 위한 이메일을 전송합니다."
101+
)
68102
public ApiResponse<String> requestReset(@AuthenticationPrincipal CustomUserDetails memberDetails) throws MessagingException {
69103
memberService.requestPasswordChange(memberDetails.getId());
70104
return ApiResponse.ok("성공적으로 비밀번호 요청메일이 전송되었습니다.");
71-
72105
}
73106

74107
@PutMapping("/reset-password")
108+
@Operation(
109+
summary = "비밀번호 재설정",
110+
description = "비밀번호를 재설정합니다."
111+
)
75112
public ApiResponse<String> resetPassword(@RequestParam String token, @AuthenticationPrincipal CustomUserDetails memberDetails, @RequestBody MemberPasswordChangeRequest request) {
76113

77114
memberService.changePassword(token, memberDetails.getId(), request.getNewPassword(), request.getConfirmPassword());
115+
78116
return ApiResponse.ok("성공적으로 비밀번호가 변경되었습니다.");
79117
}
80-
81118
}

0 commit comments

Comments
 (0)