[BE] docs: 답변 하이라이트 API 문서 작성 #800

donghoony · 2024-10-08T15:35:29Z

resolves [BE] 형광펜 추가 API 문서 작성 #795

DTO 네이밍은 아래와 같습니다.

HighlightsRequest: 전체 하이라이트 배열
HighlightRequest: 하이라이트 한 개의 정보
HighlightedLineRequest: 개행문자(\n)으로 구분되는 한 줄에 대한 정보
HighlightIndexRangeRequest: (startIndex, endIndex) 에 대한 정보

🚀 어떤 기능을 구현했나요 ?

형광펜? 하이라이트? 코드에서는 하이라이트라고 했으니 그렇게 용어를 통일합니다.
하이라이트 추가 기능에 대한 API 뼈대를 만들었습니다. 이는 추가, 삭제, 변경을 모두 포함하지 않을까 생각해요.

🔥 어떻게 해결했나요 ?

DTO 만들기, 서비스 및 컨트롤러 + RestDocs

📝 어떤 부분에 집중해서 리뷰해야 할까요?

언제나 그랬듯이 Dto 네이밍을 봐주시면 감사하겠습니다.

github-actions · 2024-10-08T15:36:58Z

Test Results

116 tests +1 116 ✅ +1 4s ⏱️ -1s
45 suites +1 0 💤 ±0
45 files +1 0 ❌ ±0

Results for commit 485b67c. ± Comparison against base commit 65bdfb3.

♻️ This comment has been updated with latest results.

skylar1220

아루 이제 레독은 눈감고도 쓰겠다~~
소소 알씨 남기고 갑니다 총총🐦‍⬛

skylar1220 · 2024-10-09T04:35:46Z

backend/src/docs/asciidoc/highlight-answers.adoc

@@ -0,0 +1,3 @@
+==== 리뷰 하이라이트 변경 (추가, 삭제, 수정 포함)
+
+operation::highlight-answer[snippets="curl-request,http-response,request-fields"]


request-cookies가 추가되어야겠네요!

skylar1220 · 2024-10-09T04:41:52Z

backend/src/main/java/reviewme/highlight/controller/HighlightController.java

+    @PostMapping("/v2/highlight")
+    public ResponseEntity<Void> highlight(@Valid @RequestBody HighlightsRequest request) {
+        highlightService.highlight(request);
+        return ResponseEntity.ok().build();


자원 개념으로 보았을 때 새로운 자원이 생성되었는데 created가 아닌 ok를 쓴 이유가 궁금해요!

생성 뿐만 아니라 수정 또한 이 API에서 일어납니다~

skylar1220 · 2024-10-09T04:43:14Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightedLineRequest.java

+public record HighlightedLineRequest(
+
+        @NotNull(message = "인덱스를 입력해주세요.")
+        Long index,


(나머지 request도 동일하게) long 타입이어도 되지 않을까요?

request라 null이 들어올 수 있슴다~!

아차차😂

skylar1220 · 2024-10-09T04:53:54Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightsRequest.java

+public record HighlightsRequest(
+
+        @NotNull(message = "하이라이트할 부분을 입력해주세요.")
+        List<HighlightRequest> highlights
+) {


현재는 각각 상위, 하위 dto가 여러 Highlight에 대한 dto, 하나의 Highlight에 대한 dto의 느낌의 네이밍인데,
Highlight가 question당 달린 하이라이트를 말하는 건지, answer 당 달린 하이라이트를 말하는 건지, line당을 말하는 건지 헷갈릴 수 있다고 생각해요!

따라서 현재 dto는 각 answer에 대한 하이라이트를 리스트로 갖고있는 dto이고, 하위 dto는 하나의 answer에 대한 하이라이트를 갖는 dto라는 의미를 담아 이런 네이밍은 어떨까요?

HighlightsRequest → AnswersHighlightRequest
HighlightRequest → AnswerHighlightRequest

네이밍에서 Answer에 대한 의존이 필요할까요? 하이라이트 그 자체의 자원 생성에 대해서만 보았어요.

하이라이트 자체의 자원 생성에 있어서도 Highlight 테이블 내에 answerId가 있는 만큼 하이라이트-answer는 의존이 강하다고 생각했어요!
더불어 전 서비스, 컨트롤러에서 반환타입으로 해당 dto의 이름을 보았을 때 잘 이해가 되어야한다를 기준으로 생각했을 때 이런 네이밍이 어떨까 생각했는데, 이건 다른 사람들 의견도 궁금합니다!

저는 여기에 대해서는 강한 주장이 생기지 않는 것 같습니다😅 두 의견 다 일리가 있다고 생각해요.

Kimprodp

심플 코멘트 확인 후 어프룹 할게요~

Kimprodp · 2024-10-09T05:11:16Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightsRequest.java

+public record HighlightsRequest(
+
+        @NotNull(message = "하이라이트할 부분을 입력해주세요.")
+        List<HighlightRequest> highlights


빈 리스트가 오는 것도 막는 것이 나을까요?

삭제 요청을 같은 API에서 하니 빈 리스트도 괜찮지 않을까? 라는 생각입니다

삭제 요청을 같은 API에서 하니 빈 리스트도 괜찮지 않을까?

어떤 뜻인지 좀 더 설명해줄 수 있나요?
프론트에서 보낸다면 절대 빈 리스트가 들어올 수 없는데, 빈 리스트가 들어왔다면 잘못된 형식의 요청이니 dto에서 막는 게 맞다고 생각해서요!

요청으로 항상 덮어쓴다고 생각하면 편할 듯 합니다 😁 빈 리스트가 들어온다면 하이라이트를 하나도 안 칠한 경우예요

Kimprodp · 2024-10-09T05:13:10Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightRequest.java

+        Long answerId,
+
+        @NotNull(message = "하이라이트 된 라인을 입력해주세요.")
+        List<HighlightedLineRequest> lines


이 부분도 빈 리스트 받지 않는 게 좋을 것 같아요

위 답변과 같아요~!

Kimprodp · 2024-10-09T05:18:05Z

backend/src/main/java/reviewme/highlight/controller/HighlightController.java

+    private final HighlightService highlightService;
+
+    @PostMapping("/v2/highlight")
+    public ResponseEntity<Void> highlight(@Valid @RequestBody HighlightsRequest request) {


세션 reviewRequestCode는 api 작성에서는 안 붙혀도 되는가요? (레독 잘 모릅니다...)

세션은 클라이언트 입장에서 JSESSIONID로만 구분해요. 이미 반영돼 있습니다 👍🏻

@SessionAttribute("reviewRequestCode") String reviewRequestCode 이거 인자로 추가할 필욘 없나요?

으엉 그거 말한거였네요 😢

Kimprodp

👍👍👍 빨리 하이라이트 치고싶다~

nayonsoso

Valid 어노테이션 부분만 확인해주세용~
그리고 request 패키지 하위에 있는 것들 중에서 이거 없는 친구들에도 이번에 다 붙여주면 좋을 것 같아요 🙏

nayonsoso · 2024-10-09T06:34:58Z

backend/src/main/java/reviewme/highlight/controller/HighlightController.java

+    private final HighlightService highlightService;
+
+    @PostMapping("/v2/highlight")
+    public ResponseEntity<Void> highlight(@Valid @RequestBody HighlightsRequest request) {


@SessionAttribute("reviewRequestCode") String reviewRequestCode 이거 인자로 추가할 필욘 없나요?

nayonsoso · 2024-10-09T06:51:41Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightsRequest.java

+public record HighlightsRequest(
+
+        @NotNull(message = "하이라이트할 부분을 입력해주세요.")
+        List<HighlightRequest> highlights
+) {


저는 여기에 대해서는 강한 주장이 생기지 않는 것 같습니다😅 두 의견 다 일리가 있다고 생각해요.

nayonsoso · 2024-10-09T06:54:27Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightsRequest.java

+        @NotNull(message = "하이라이트할 부분을 입력해주세요.")
+        List<HighlightRequest> highlights


validation annotation 이 붙은 컬렉션의 각 원소에도 valid 검증을 하기 위해서는 여기에됴 @Valid 붙여줘야 합니다!

Suggested change

@NotNull(message = "하이라이트할 부분을 입력해주세요.")

List<HighlightRequest> highlights

@NotNull(message = "하이라이트할 부분을 입력해주세요.") @Valid

List<HighlightRequest> highlights

지금은 아래 요청이 통과되네요

헉 그럼 다른데에도 붙여줘야겠네요? 확인해보니 속에는 안 붙인데가 있는데
예: ReviewRegisterRequest 속의 ReviewAnswerRequest를 위해서 붙여야함

네네 그래서 이번에 싹 다 붙여도 될 것 같아용~

skylar1220

하나 더 질문 남겨요~~

skylar1220 · 2024-10-09T10:20:56Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightsRequest.java

+public record HighlightsRequest(
+
+        @NotNull(message = "하이라이트할 부분을 입력해주세요.")
+        List<HighlightRequest> highlights


삭제 요청을 같은 API에서 하니 빈 리스트도 괜찮지 않을까?

어떤 뜻인지 좀 더 설명해줄 수 있나요?
프론트에서 보낸다면 절대 빈 리스트가 들어올 수 없는데, 빈 리스트가 들어왔다면 잘못된 형식의 요청이니 dto에서 막는 게 맞다고 생각해서요!

skylar1220

아루 하나만 더 확인 부탁해욧!!!

skylar1220 · 2024-10-09T12:22:10Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightRequest.java

+        Long answerId,
+
+        @Valid @NotNull(message = "하이라이트 된 라인을 입력해주세요.")
+        List<HighlightedLineRequest> lines


이 부분은 빈리스트를 못받게 해야하지 않을까요?
왜냐면 answerId가 있는 request의 경우 lines가 빈 리스트가 올 수 없으니까요!
answerId가 있다 → 하이라이트가 있는 부분이어서 요청에 포함되었다.

최외곽 하나가 비어있다면 그냥 무시하고, 내부로 한 번 들어가기만 하면 매핑이 되어야한다는 이야기네요. 아래 질문 내용과 함께 반영할게요 🚀

댓츠 롸잇👍

skylar1220 · 2024-10-09T12:23:42Z

backend/src/main/java/reviewme/highlight/service/dto/HighlightedLineRequest.java

+        @Valid @NotNull(message = "하이라이트 범위를 입력해주세요.")
+        List<HighlightIndexRangeRequest> ranges


위와 같은 맥락으로 이 부분도 빈리스트를 못받게 해야하지 않을까요?
왜냐면 index가 있는 request의 경우 ranges가 빈 리스트가 올 수 없으니까요!
index가 있다 → 하이라이트가 있는 부분이어서 요청에 포함되었다.

skylar1220

DTO명 나중에~~~
머지하고 바톤터치합시당🏃🏃🏃 수고했어여!!!

nayonsoso

어푸어푸!!!
고려할게 많았었는데, 고생했어요🌷

* feat: 하이라이트 요청 dto 생성 * feat: 하이라이트 뼈대 코드 작성 * docs: API 문서 작성 * docs: request cookie 필드 추가 * fix: 재귀적 `@Valid` 적용 * fix: 세션 값 추가 * refactor: API에 질문 ID 필드 추가 * refactor: 비어있지 않으면 안 되는 부분들에 대한 검증 추가

donghoony added 3 commits October 9, 2024 00:32

feat: 하이라이트 요청 dto 생성

2e0a5ee

feat: 하이라이트 뼈대 코드 작성

e909b0d

docs: API 문서 작성

fe50887

donghoony added ✨ BE 📋 문서 labels Oct 8, 2024

donghoony linked an issue Oct 8, 2024 that may be closed by this pull request

[BE] 형광펜 추가 API 문서 작성 #795

Closed

donghoony self-assigned this Oct 8, 2024

donghoony requested review from nayonsoso, skylar1220 and Kimprodp October 8, 2024 15:35

donghoony added this to the 6차 스프린트: 최종장 milestone Oct 8, 2024

skylar1220 requested changes Oct 9, 2024

View reviewed changes

docs: request cookie 필드 추가

983069a

Kimprodp requested changes Oct 9, 2024

View reviewed changes

Kimprodp approved these changes Oct 9, 2024

View reviewed changes

nayonsoso requested changes Oct 9, 2024

View reviewed changes

donghoony added 2 commits October 9, 2024 15:57

fix: 재귀적 @Valid 적용

07ac8d9

fix: 세션 값 추가

bc23d3f

skylar1220 requested changes Oct 9, 2024

View reviewed changes

refactor: API에 질문 ID 필드 추가

a59e6a9

skylar1220 requested changes Oct 9, 2024

View reviewed changes

refactor: 비어있지 않으면 안 되는 부분들에 대한 검증 추가

485b67c

skylar1220 approved these changes Oct 9, 2024

View reviewed changes

nayonsoso approved these changes Oct 10, 2024

View reviewed changes

donghoony merged commit 1c5b177 into develop Oct 10, 2024
7 checks passed

donghoony deleted the be/docs/795-highlight-docs branch October 10, 2024 01:08

		@@ -0,0 +1,3 @@
		==== 리뷰 하이라이트 변경 (추가, 삭제, 수정 포함)

		operation::highlight-answer[snippets="curl-request,http-response,request-fields"]

		@NotNull(message = "하이라이트할 부분을 입력해주세요.")
		List<HighlightRequest> highlights

		@Valid @NotNull(message = "하이라이트 범위를 입력해주세요.")
		List<HighlightIndexRangeRequest> ranges

[BE] docs: 답변 하이라이트 API 문서 작성 #800

[BE] docs: 답변 하이라이트 API 문서 작성 #800

Conversation

donghoony commented Oct 8, 2024 • edited Loading

🚀 어떤 기능을 구현했나요 ?

🔥 어떻게 해결했나요 ?

📝 어떤 부분에 집중해서 리뷰해야 할까요?

github-actions bot commented Oct 8, 2024 • edited Loading

Test Results

skylar1220 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skylar1220 Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kimprodp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

donghoony Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nayonsoso Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kimprodp left a comment

Choose a reason for hiding this comment

nayonsoso left a comment

Choose a reason for hiding this comment

nayonsoso Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nayonsoso Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

skylar1220 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skylar1220 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

skylar1220 left a comment

Choose a reason for hiding this comment

nayonsoso left a comment

Choose a reason for hiding this comment

donghoony commented Oct 8, 2024 •

edited

Loading

github-actions bot commented Oct 8, 2024 •

edited

Loading

skylar1220 Oct 9, 2024 •

edited

Loading

donghoony Oct 9, 2024 •

edited

Loading

nayonsoso Oct 9, 2024 •

edited

Loading

nayonsoso Oct 9, 2024 •

edited

Loading

nayonsoso Oct 9, 2024 •

edited

Loading