Feature/#65 카테고리 등록 조회 수정 삭제 rest docs 작성 by JJimini · Pull Request #70 · PNUops/opus-backend

JJimini · 2026-02-04T13:55:17Z

🔥 연관된 이슈

close: #65
close: #66
close: #67

📜 작업 내용

카테고리 등록, 전체 조회, 수정, 삭제 API docs 작성
대회 등록, 전체 조회, 수정, 삭제 API docs 작성
분과 등록, 전체 조회, 수정, 삭제 API docs 작성

💬 리뷰 요구사항

3개 issue 한방에 했습니당
작성하면서 발견한 자잘한 수정사항들도 수정했습니다!

✨ 기타

100줄은 넘지만.. 이미 개발 완료된 API의 docs만 작성한 거라서 간단 수정 라벨 달았습니다~!
저도 다시 확인은 했는데, 복붙하면서 작업해서 오타가 있을 수도..?

- 분과 생성 - 분과 수정 - 분과 삭제 - 분과 전체 조회

sjmoon00

수고하셨습니다~
카테고리랑 분과랑 복사하는 과정에서 오타가 있는것 같습니다~

sjmoon00 · 2026-02-08T00:37:08Z

src/test/java/com/opus/opus/restdocs/docs/ContestTrackApiDocs.java

+public class ContestTrackApiDocs extends RestDocsTest {
+


클래스명에 Test 접미사가 누락된 것 같습니다

sjmoon00 · 2026-02-08T00:40:57Z

src/test/java/com/opus/opus/restdocs/docs/ContestTrackApiDocs.java

+        willThrow(new ContestCategoryException(CATEGORY_NAME_ALREADY_EXIST)).given(contestTrackCommandService)
+                .createTrack(any(), any());


ContestTrackException이 발생하지 않을까 생각합니다

sjmoon00 · 2026-02-08T00:42:37Z

src/test/java/com/opus/opus/restdocs/docs/ContestTrackApiDocs.java

+                                headerWithName(HttpHeaders.AUTHORIZATION).description("Bearer {accessToken} (관리자)")
+                        ),
+                        requestFields(
+                                stringFieldWithPath("trackName", "카테고리 이름")


오타인것 같습니다~

sjmoon00 · 2026-02-08T00:48:02Z

src/test/java/com/opus/opus/restdocs/docs/ContestTrackApiDocs.java

+    @DisplayName("[성공] 유효한 요청이면 대회 카테고리 전체 조회는 성공한다.")
+    void 유효한_요청이면_대회_카테고리_전체_조회는_성공한다() throws Exception {


메서드명, @DisplayName에 카테고리라는 명칭이 잘못 들어간것 같습니다

sjmoon00 · 2026-02-08T00:49:36Z

src/test/java/com/opus/opus/restdocs/docs/ContestCategoryApiDocsTest.java

+
+    @Test
+    @DisplayName("[실패] 이미 카테고리 이름이 존재한다면 에러를 반환한다.")
+    void 이미_카테코리_이름이_존재한다면_에러를_반환한다() throws Exception {


카테코리 오타 있습니다 😄

sjmoon00 · 2026-02-08T01:19:02Z

src/main/java/com/opus/opus/docs/asciidoc/contest.adoc

+
+==== ⚠️ 실패 케이스
+
+.❌ Case 1: 동일한 카테고리 이름 존재


동일한 대회명인것 같습니다

sjmoon00 · 2026-02-08T01:20:35Z

src/main/java/com/opus/opus/docs/asciidoc/contest-track.adoc

+
+== `PATCH`: 대회 분과 수정
+
+NOTE: 대회 분과 생성과 동일하게 이미 저장되어 있는 카테고리 이름은 저장 불가


여기도 분과 이름인것 같습니다

- ContestTrackApiDocs -> ContestTrackApiDocsTest

pykido

수고하셨습니다! 간단한 리뷰 확인 부탁드려요~!

pykido · 2026-02-08T12:25:40Z

src/main/java/com/opus/opus/docs/asciidoc/contest-category.adoc

+.HTTP Response
+include::{snippets}/delete-contest-category/http-response.adoc[]
+
+.Path Parameters


API 명세서를 보면 보통 아래와 같은 순서인데 Path Parameters를 Response보다 앞쪽에 배치시키는건 어떤가요-?

Request Header

Path Parameters

Request Fields

Response

pykido · 2026-02-08T12:27:15Z

src/test/java/com/opus/opus/restdocs/docs/ContestTrackApiDocsTest.java

+    void 유효한_요청이면_대회_분과_생성은_성공한다() throws Exception {
+        doNothing().when(contestTrackCommandService).createTrack(any(), any());
+
+        mockMvc.perform(post("/contests/{contestId}/tracks", 1)


매직 넘버를 사용하기보다 아래와 같이 변수를 사용하는건 어떨까요~?

private static final Long CONTEST_ID = 1L; private static final Long TRACK_ID = 1L;

좋은 방식인 것 같습니다!
그런데 현재 다른 모든 코드에서 urlVariables를 매직넘버를 사용하고 있어서 전체적인 수정이 필요해보입니다.
해당 부분은 추후 good first issue로 만들어서 수정하는 것은 어떨까요??

좋습니다~!!

sjmoon00

수고하셨습니다~

JJimini added 9 commits February 4, 2026 17:21

docs: 카테고리 등록 문서 작성

c48e1c7

docs: 카테고리 수정 문서화

c55ef7d

docs: 대회 카테고리 삭제 문서화

7f496da

docs: 카테고리 전체 조회 문서화

4fe588c

docs: 대회 생성 문서화

dba6a31

docs: 대회 수정 문서화

3d0b761

docs: 대회 삭제 문서화

e58c0fe

docs: 대회 목록 조회 문서화

93d0055

docs: 분과 관련 API 문서화

f67fe37

- 분과 생성 - 분과 수정 - 분과 삭제 - 분과 전체 조회

JJimini requested review from myeowon, pykido and sjmoon00 February 4, 2026 13:55

JJimini self-assigned this Feb 4, 2026

JJimini added the 🕐 간단 수정 수정 코드 100줄 이하의 간단한 수정 label Feb 4, 2026

chore: 분류 세분화

9cc7b28

sjmoon00 requested changes Feb 8, 2026

View reviewed changes

JJimini added 3 commits February 8, 2026 19:40

chore: class명 오타 수정

e3afe43

- ContestTrackApiDocs -> ContestTrackApiDocsTest

fix: Exception message 수정

4f6098a

chore: 오타수정

144437a

JJimini requested a review from sjmoon00 February 8, 2026 10:55

pykido reviewed Feb 8, 2026

View reviewed changes

chore: path parameters 위치 변경

0bb3191

sjmoon00 approved these changes Feb 9, 2026

View reviewed changes

		willThrow(new ContestCategoryException(CATEGORY_NAME_ALREADY_EXIST)).given(contestTrackCommandService)
		.createTrack(any(), any());

		@DisplayName("[성공] 유효한 요청이면 대회 카테고리 전체 조회는 성공한다.")
		void 유효한_요청이면_대회_카테고리_전체_조회는_성공한다() throws Exception {


		==== ⚠️ 실패 케이스

		.❌ Case 1: 동일한 카테고리 이름 존재


		== `PATCH`: 대회 분과 수정

		NOTE: 대회 분과 생성과 동일하게 이미 저장되어 있는 카테고리 이름은 저장 불가

Conversation

JJimini commented Feb 4, 2026

🔥 연관된 이슈

📜 작업 내용

💬 리뷰 요구사항

✨ 기타

Uh oh!

sjmoon00 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pykido left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sjmoon00 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants