Skip to content

Commit 9b1ac36

Browse files
why-only-englishwhy-only-english
authored
Merge pull request #290 from ttoklip/Docs/12-refactoring-specification
pr docs: 명세서 가독성 개선
2 parents e5207d4 + f25d41e commit 9b1ac36

File tree

50 files changed

+1892
-1656
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+1892
-1656
lines changed

‎ttoklip-api/src/main/java/com/api/auth/local/presentation/LocalAuthController.java‎

Lines changed: 10 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,65 +4,39 @@
44
import com.api.global.support.response.Message;
55
import com.api.global.support.response.TtoklipResponse;
66
import com.domain.term.response.TermSignUpResponse;
7-
import io.swagger.v3.oas.annotations.Operation;
8-
import io.swagger.v3.oas.annotations.responses.ApiResponses;
9-
import io.swagger.v3.oas.annotations.tags.Tag;
107
import lombok.RequiredArgsConstructor;
118
import org.springframework.http.MediaType;
129
import org.springframework.validation.annotation.Validated;
13-
import org.springframework.web.bind.annotation.GetMapping;
14-
import org.springframework.web.bind.annotation.ModelAttribute;
15-
import org.springframework.web.bind.annotation.PostMapping;
16-
import org.springframework.web.bind.annotation.RequestBody;
17-
import org.springframework.web.bind.annotation.RequestMapping;
18-
import org.springframework.web.bind.annotation.RequestParam;
19-
import org.springframework.web.bind.annotation.RestController;
10+
import org.springframework.web.bind.annotation.*;
2011

21-
@Tag(name = "Auth", description = "회원가입/로그인 관련 API")
22-
@RestController
2312
@RequiredArgsConstructor
13+
@RestController
2414
@RequestMapping("/api/v1/auth")
25-
public class LocalAuthController {
15+
public class LocalAuthController implements LocalAuthControllerDocs {
2616

2717
private final AuthFacade authFacade;
2818

29-
/* --------------------------------- signup --------------------------------- */
30-
@Operation(summary = "회원가입", description = "직접 회원가입을 진행합니다.")
31-
@ApiResponses(value = {
32-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "회원가입 성공")
33-
})
19+
@Override
3420
@PostMapping(value = "/signup", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
35-
public TtoklipResponse<Message> signup(
36-
final @Validated @ModelAttribute LocalMemberWebCreate request
21+
public TtoklipResponse<Message> signup(@Validated @ModelAttribute LocalMemberWebCreate request
3722
) {
3823
return new TtoklipResponse<>(authFacade.signup(request));
3924
}
4025

41-
/* --------------------------------- duplicate --------------------------------- */
42-
@Operation(summary = "중복확인", description = "아이디 중복확인을 진행합니다.")
43-
@ApiResponses(value = {
44-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "회원가입 성공")
45-
})
26+
@Override
4627
@PostMapping("/duplicate")
47-
public TtoklipResponse<Message> duplicate(final @RequestParam String newId) {
28+
public TtoklipResponse<Message> duplicate(@RequestParam String newId) {
4829
return new TtoklipResponse<>(authFacade.duplicate(newId));
4930
}
5031

51-
/* --------------------------------- login --------------------------------- */
52-
@Operation(summary = "로그인", description = "직접 로그인을 진행합니다.")
53-
@ApiResponses(value = {
54-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "로그인 성공")
55-
})
32+
@Override
5633
@PostMapping("/login")
57-
public TtoklipResponse<AuthLoginResponse> login(final @RequestBody AuthLogin authLogin) {
34+
public TtoklipResponse<AuthLoginResponse> login(@RequestBody AuthLogin authLogin) {
5835
AuthLoginResponse response = authFacade.login(authLogin);
5936
return new TtoklipResponse<>(response);
6037
}
6138

62-
@Operation(summary = "회원가입 전용 이용약관 조회", description = "회원가입 전 이용약관을 조회하는 API입니다.")
63-
@ApiResponses(value = {
64-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "이용약관 조회 성공")
65-
})
39+
@Override
6640
@GetMapping("/agree")
6741
public TtoklipResponse<TermSignUpResponse> getTermSignUp() {
6842
TermSignUpResponse response = authFacade.getTermWhenSignUp();

‎ttoklip-api/src/main/java/com/api/auth/local/presentation/LocalAuthControllerDocs.java‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
package com.api.auth.local.presentation;
2+
3+
import com.api.global.support.response.Message;
4+
import com.api.global.support.response.TtoklipResponse;
5+
import com.domain.term.response.TermSignUpResponse;
6+
import io.swagger.v3.oas.annotations.Operation;
7+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
8+
import io.swagger.v3.oas.annotations.tags.Tag;
9+
import org.springframework.validation.annotation.Validated;
10+
import org.springframework.web.bind.annotation.ModelAttribute;
11+
import org.springframework.web.bind.annotation.RequestBody;
12+
import org.springframework.web.bind.annotation.RequestParam;
13+
14+
@Tag(name = "Auth", description = "회원가입/로그인 관련 API")
15+
public interface LocalAuthControllerDocs {
16+
17+
@Operation(summary = "회원가입", description = "직접 회원가입을 진행합니다.")
18+
@ApiResponses(value = {
19+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "회원가입 성공")
20+
})
21+
TtoklipResponse<Message> signup(@Validated @ModelAttribute LocalMemberWebCreate request);
22+
23+
@Operation(summary = "중복확인", description = "아이디 중복확인을 진행합니다.")
24+
@ApiResponses(value = {
25+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "회원가입 성공")
26+
})
27+
TtoklipResponse<Message> duplicate(@RequestParam String newId);
28+
29+
@Operation(summary = "로그인", description = "직접 로그인을 진행합니다.")
30+
@ApiResponses(value = {
31+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "로그인 성공")
32+
})
33+
TtoklipResponse<AuthLoginResponse> login(@RequestBody AuthLogin authLogin);
34+
35+
@Operation(summary = "회원가입 전용 이용약관 조회", description = "회원가입 전 이용약관을 조회하는 API입니다.")
36+
@ApiResponses(value = {
37+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "이용약관 조회 성공")
38+
})
39+
TtoklipResponse<TermSignUpResponse> getTermSignUp();
40+
}

‎ttoklip-api/src/main/java/com/api/auth/oauth2/presentation/OAuthController.java‎

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

33
import com.api.auth.oauth2.application.OAuthFacade;
44
import com.api.global.support.response.TtoklipResponse;
5-
import com.api.profile.presentation.PrivacyConstant;
6-
import io.swagger.v3.oas.annotations.Operation;
7-
import io.swagger.v3.oas.annotations.media.Content;
8-
import io.swagger.v3.oas.annotations.media.ExampleObject;
9-
import io.swagger.v3.oas.annotations.media.Schema;
10-
import io.swagger.v3.oas.annotations.responses.ApiResponses;
115
import lombok.RequiredArgsConstructor;
12-
import org.springframework.http.MediaType;
136
import org.springframework.web.bind.annotation.PostMapping;
147
import org.springframework.web.bind.annotation.RequestBody;
158
import org.springframework.web.bind.annotation.RequestMapping;
169
import org.springframework.web.bind.annotation.RestController;
1710

18-
@RestController
1911
@RequiredArgsConstructor
12+
@RestController
2013
@RequestMapping("/api/v1/oauth")
21-
public class OAuthController {
14+
public class OAuthController implements OAuthControllerDocs {
15+
2216
private final OAuthFacade oAuthFacade;
2317

24-
@Operation(summary = "Server 자체 로그인", description = "oauth accessToken으로 로그인",
25-
tags = {"Authentication"})
26-
@ApiResponses(value = {
27-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "oauth accessToken으로 로그인",
28-
content = @Content(
29-
mediaType = MediaType.APPLICATION_JSON_VALUE,
30-
schema = @Schema(implementation = TtoklipResponse.class),
31-
examples = @ExampleObject(
32-
name = "SuccessResponse",
33-
value = PrivacyConstant.LOGIN_SUCCESS,
34-
description = "로그인"
35-
)))})
18+
@Override
3619
@PostMapping
37-
public TtoklipResponse<OAuthLoginResponse> login(final @RequestBody OAuthLogin request) {
20+
public TtoklipResponse<OAuthLoginResponse> login(@RequestBody OAuthLogin request) {
3821
OAuthLoginResponse response = oAuthFacade.authenticate(request);
3922
return new TtoklipResponse<>(response);
4023
}

‎ttoklip-api/src/main/java/com/api/auth/oauth2/presentation/OAuthControllerDocs.java‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
package com.api.auth.oauth2.presentation;
2+
3+
import com.api.global.support.response.TtoklipResponse;
4+
import com.api.profile.presentation.PrivacyConstant;
5+
import io.swagger.v3.oas.annotations.Operation;
6+
import io.swagger.v3.oas.annotations.media.Content;
7+
import io.swagger.v3.oas.annotations.media.ExampleObject;
8+
import io.swagger.v3.oas.annotations.media.Schema;
9+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
10+
import io.swagger.v3.oas.annotations.tags.Tag;
11+
import org.springframework.http.MediaType;
12+
import org.springframework.web.bind.annotation.RequestBody;
13+
14+
@Tag(name = "OAuth", description = "Server 자체 로그인 API")
15+
public interface OAuthControllerDocs {
16+
17+
@Operation(summary = "Server 자체 로그인 API", description = "oauth accessToken으로 로그인을 처리하는 API입니다.", tags = {"Authentication"})
18+
@ApiResponses(value = {
19+
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "oauth accessToken으로 로그인",
20+
content = @Content(
21+
mediaType = MediaType.APPLICATION_JSON_VALUE,
22+
schema = @Schema(implementation = TtoklipResponse.class),
23+
examples = @ExampleObject(
24+
name = "SuccessResponse",
25+
value = PrivacyConstant.LOGIN_SUCCESS,
26+
description = "로그인 성공 예시"
27+
)))})
28+
TtoklipResponse<OAuthLoginResponse> login(@RequestBody OAuthLogin request);
29+
}

‎ttoklip-api/src/main/java/com/api/builtin/presentation/BulletinController.java‎

Lines changed: 14 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -3,124 +3,56 @@
33
import com.api.builtin.application.NoticeFacade;
44
import com.api.global.support.response.Message;
55
import com.api.global.support.response.TtoklipResponse;
6-
import com.api.global.util.SecurityUtil;
76
import com.domain.bulletin.domain.NoticeCreate;
87
import com.domain.bulletin.domain.NoticeEdit;
98
import com.domain.bulletin.domain.NoticeResponse;
109
import com.domain.bulletin.domain.NoticeResponses;
11-
import io.swagger.v3.oas.annotations.Operation;
12-
import io.swagger.v3.oas.annotations.Parameter;
13-
import io.swagger.v3.oas.annotations.media.Content;
14-
import io.swagger.v3.oas.annotations.media.ExampleObject;
15-
import io.swagger.v3.oas.annotations.media.Schema;
16-
import io.swagger.v3.oas.annotations.responses.ApiResponses;
17-
import io.swagger.v3.oas.annotations.tags.Tag;
10+
import com.api.global.util.SecurityUtil;
1811
import lombok.RequiredArgsConstructor;
1912
import org.springframework.http.MediaType;
2013
import org.springframework.validation.annotation.Validated;
21-
import org.springframework.web.bind.annotation.DeleteMapping;
22-
import org.springframework.web.bind.annotation.GetMapping;
23-
import org.springframework.web.bind.annotation.PatchMapping;
24-
import org.springframework.web.bind.annotation.PathVariable;
25-
import org.springframework.web.bind.annotation.PostMapping;
26-
import org.springframework.web.bind.annotation.RequestBody;
27-
import org.springframework.web.bind.annotation.RequestMapping;
28-
import org.springframework.web.bind.annotation.RequestParam;
29-
import org.springframework.web.bind.annotation.RestController;
14+
import org.springframework.web.bind.annotation.*;
3015

31-
@Tag(name = "Notice", description = "공지사항 api입니다")
3216
@RequiredArgsConstructor
3317
@RestController
3418
@RequestMapping("/api/v1/notice")
35-
public class BulletinController {
19+
public class BulletinController implements BulletinControllerDocs {
3620

37-
private final static int PAGE_SIZE = 10; // 페이지 당 데이터 수
3821
private final NoticeFacade noticeFacade;
22+
private final static int PAGE_SIZE = 10;
3923

40-
@Operation(summary = "모든 공지사항 불러오기", description = "공지사항 목록을 가져옵니다")
41-
@ApiResponses(value = {
42-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "공지사항 조회 성공",
43-
content = @Content(
44-
mediaType = "application/json",
45-
schema = @Schema(implementation = TtoklipResponse.class),
46-
examples = @ExampleObject(
47-
name = "SuccessResponse",
48-
value = NotiConstant.noticeResponse,
49-
description = "공지사항이 조회되었습니다"
50-
)))})
24+
@Override
5125
@GetMapping
5226
public TtoklipResponse<NoticeResponses> getNoticeList(
53-
@Parameter(description = "페이지 번호 (0부터 시작, 기본값 0)", example = "0")
54-
@RequestParam(required = false, defaultValue = "0") final int page) {
27+
@RequestParam(required = false, defaultValue = "0") int page) {
5528
NoticeResponses noticeResponses = noticeFacade.getNoticeList(page, PAGE_SIZE);
5629
return new TtoklipResponse<>(noticeResponses);
5730
}
5831

59-
@Operation(summary = "공지사항 생성", description = "공지사항을 만듭니다")
60-
@ApiResponses(value = {
61-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "공지사항 생성 성공",
62-
content = @Content(
63-
mediaType = MediaType.APPLICATION_JSON_VALUE,
64-
schema = @Schema(implementation = TtoklipResponse.class),
65-
examples = @ExampleObject(
66-
name = "SuccessResponse",
67-
value = NotiConstant.createNoticeResponse,
68-
description = "공지사항이 생성되었습니다"
69-
)))})
32+
@Override
7033
@PostMapping(value = "/create", consumes = MediaType.APPLICATION_JSON_VALUE)
71-
public TtoklipResponse<Message> register(final @Validated @RequestBody NoticeCreate request) {
34+
public TtoklipResponse<Message> register(@Validated @RequestBody NoticeCreate request) {
7235
Message message = noticeFacade.register(request);
7336
return new TtoklipResponse<>(message);
7437
}
7538

76-
@Operation(summary = "공지사항 조회", description = "공지사항 ID에 해당하는 공지사항을 조회합니다.")
77-
@ApiResponses(value = {
78-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "공지사항 성공",
79-
content = @Content(
80-
mediaType = MediaType.APPLICATION_JSON_VALUE,
81-
schema = @Schema(implementation = TtoklipResponse.class),
82-
examples = @ExampleObject(
83-
name = "SuccessResponse",
84-
value = NotiConstant.singleNoticeResponse,
85-
description = "공지사항이 조회되었습니다."
86-
)))})
39+
@Override
8740
@GetMapping("/{noticeId}")
88-
public TtoklipResponse<NoticeResponse> getSingleNotice(final @PathVariable Long noticeId) {
41+
public TtoklipResponse<NoticeResponse> getSingleNotice(@PathVariable Long noticeId) {
8942
NoticeResponse singleNotice = noticeFacade.getSingleNotice(noticeId);
9043
return new TtoklipResponse<>(singleNotice);
9144
}
9245

93-
@Operation(summary = "공지사항 삭제", description = "공지사항 ID에 해당하는 공지사항을 삭제합니다.")
94-
@ApiResponses(value = {
95-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "공지사항 삭제 성공",
96-
content = @Content(
97-
mediaType = MediaType.APPLICATION_JSON_VALUE,
98-
schema = @Schema(implementation = TtoklipResponse.class),
99-
examples = @ExampleObject(
100-
name = "SuccessResponse",
101-
value = NotiConstant.deleteNoticeResponse,
102-
description = "공지사항을 삭제하였습니다"
103-
)))})
46+
@Override
10447
@DeleteMapping("/{noticeId}")
105-
public TtoklipResponse<Message> deleteNotice(final @PathVariable Long noticeId) {
48+
public TtoklipResponse<Message> deleteNotice(@PathVariable Long noticeId) {
10649
Message message = noticeFacade.delete(noticeId);
10750
return new TtoklipResponse<>(message);
10851
}
10952

110-
@Operation(summary = "공지사항 수정", description = "공지사항 ID에 해당하는 공지사항을 수정합니다.")
111-
@ApiResponses(value = {
112-
@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "공지사항 수정 성공",
113-
content = @Content(
114-
mediaType = MediaType.APPLICATION_JSON_VALUE,
115-
schema = @Schema(implementation = TtoklipResponse.class),
116-
examples = @ExampleObject(
117-
name = "SuccessResponse",
118-
value = NotiConstant.updateNoticeResponse,
119-
description = "공지사항이 수정되었습니다."
120-
)))})
53+
@Override
12154
@PatchMapping("/{noticeId}")
122-
public TtoklipResponse<Message> edit(final @PathVariable Long noticeId,
123-
final @RequestBody NoticeEdit request) {
55+
public TtoklipResponse<Message> edit(@PathVariable Long noticeId, @RequestBody NoticeEdit request) {
12456
Long currentMemberId = SecurityUtil.getCurrentMember().getId();
12557
Message message = noticeFacade.edit(noticeId, request, currentMemberId);
12658
return new TtoklipResponse<>(message);

0 commit comments

Comments
 (0)