Skip to content

Commit 6d41c04

Browse files
joyewon0705joyewon0705
committed
Docs: Swagger 문서 작성
1 parent 7a38012 commit 6d41c04

File tree

1 file changed

+138
-1
lines changed

1 file changed

+138
-1
lines changed

‎src/main/java/com/back/domain/board/controller/CommentControllerDocs.java‎

Lines changed: 138 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,144 @@
11
package com.back.domain.board.controller;
22

3+
import com.back.domain.board.dto.CommentRequest;
4+
import com.back.domain.board.dto.CommentResponse;
5+
import com.back.global.common.dto.RsData;
6+
import com.back.global.security.user.CustomUserDetails;
7+
import io.swagger.v3.oas.annotations.Operation;
8+
import io.swagger.v3.oas.annotations.media.Content;
9+
import io.swagger.v3.oas.annotations.media.ExampleObject;
10+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
11+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
312
import io.swagger.v3.oas.annotations.tags.Tag;
13+
import org.springframework.http.ResponseEntity;
14+
import org.springframework.security.core.annotation.AuthenticationPrincipal;
15+
import org.springframework.web.bind.annotation.*;
416

517
@Tag(name = "Comment API", description = "댓글 관련 API")
618
public interface CommentControllerDocs {
7-
}
19+
20+
@Operation(
21+
summary = "댓글 생성",
22+
description = "로그인한 사용자가 특정 게시글에 댓글을 작성합니다."
23+
)
24+
@ApiResponses({
25+
@ApiResponse(
26+
responseCode = "201",
27+
description = "댓글 생성 성공",
28+
content = @Content(
29+
mediaType = "application/json",
30+
examples = @ExampleObject(value = """
31+
{
32+
"success": true,
33+
"code": "SUCCESS_200",
34+
"message": "댓글이 생성되었습니다.",
35+
"data": {
36+
"commentId": 25,
37+
"postId": 101,
38+
"author": {
39+
"id": 5,
40+
"nickname": "홍길동"
41+
},
42+
"content": "좋은 글 감사합니다!",
43+
"createdAt": "2025-09-22T11:30:00",
44+
"updatedAt": "2025-09-22T11:30:00"
45+
}
46+
}
47+
""")
48+
)
49+
),
50+
@ApiResponse(
51+
responseCode = "400",
52+
description = "잘못된 요청 (필드 누락 등)",
53+
content = @Content(
54+
mediaType = "application/json",
55+
examples = @ExampleObject(value = """
56+
{
57+
"success": false,
58+
"code": "COMMON_400",
59+
"message": "잘못된 요청입니다.",
60+
"data": null
61+
}
62+
""")
63+
)
64+
),
65+
@ApiResponse(
66+
responseCode = "401",
67+
description = "인증 실패 (토큰 없음/잘못됨/만료)",
68+
content = @Content(
69+
mediaType = "application/json",
70+
examples = {
71+
@ExampleObject(name = "토큰 없음", value = """
72+
{
73+
"success": false,
74+
"code": "AUTH_001",
75+
"message": "인증이 필요합니다.",
76+
"data": null
77+
}
78+
"""),
79+
@ExampleObject(name = "잘못된 토큰", value = """
80+
{
81+
"success": false,
82+
"code": "AUTH_002",
83+
"message": "유효하지 않은 액세스 토큰입니다.",
84+
"data": null
85+
}
86+
"""),
87+
@ExampleObject(name = "만료된 토큰", value = """
88+
{
89+
"success": false,
90+
"code": "AUTH_004",
91+
"message": "만료된 액세스 토큰입니다.",
92+
"data": null
93+
}
94+
""")
95+
}
96+
)
97+
),
98+
@ApiResponse(
99+
responseCode = "404",
100+
description = "존재하지 않는 사용자 또는 게시글",
101+
content = @Content(
102+
mediaType = "application/json",
103+
examples = {
104+
@ExampleObject(name = "존재하지 않는 사용자", value = """
105+
{
106+
"success": false,
107+
"code": "USER_001",
108+
"message": "존재하지 않는 사용자입니다.",
109+
"data": null
110+
}
111+
"""),
112+
@ExampleObject(name = "존재하지 않는 게시글", value = """
113+
{
114+
"success": false,
115+
"code": "POST_001",
116+
"message": "존재하지 않는 게시글입니다.",
117+
"data": null
118+
}
119+
""")
120+
}
121+
)
122+
),
123+
@ApiResponse(
124+
responseCode = "500",
125+
description = "서버 내부 오류",
126+
content = @Content(
127+
mediaType = "application/json",
128+
examples = @ExampleObject(value = """
129+
{
130+
"success": false,
131+
"code": "COMMON_500",
132+
"message": "서버 오류가 발생했습니다.",
133+
"data": null
134+
}
135+
""")
136+
)
137+
)
138+
})
139+
ResponseEntity<RsData<CommentResponse>> createComment(
140+
@PathVariable Long postId,
141+
@RequestBody CommentRequest request,
142+
@AuthenticationPrincipal CustomUserDetails user
143+
);
144+
}

0 commit comments

Comments
 (0)