Skip to content

Commit c3ee228

Browse files
joyewon0705joyewon0705
committed
Docs: Swagger 문서 작성
1 parent 4714a9a commit c3ee228

File tree

2 files changed

+148
-1
lines changed

2 files changed

+148
-1
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
@RestController
1616
@RequestMapping("/api/posts")
1717
@RequiredArgsConstructor
18-
public class PostController {
18+
public class PostController implements PostControllerDocs {
1919
private final PostService postService;
2020

2121
// 게시글 생성

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

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
package com.back.domain.board.controller;
2+
3+
import com.back.domain.board.dto.PostRequest;
4+
import com.back.domain.board.dto.PostResponse;
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;
12+
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.RequestBody;
16+
17+
@Tag(name = "Post API", description = "게시글 관련 API")
18+
public interface PostControllerDocs {
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+
"postId": 101,
37+
"author": {
38+
"id": 5,
39+
"nickname": "홍길동"
40+
},
41+
"title": "첫 번째 게시글",
42+
"content": "안녕하세요, 첫 글입니다!",
43+
"categories": [
44+
{ "id": 1, "name": "공지사항" },
45+
{ "id": 2, "name": "자유게시판" }
46+
],
47+
"createdAt": "2025-09-22T10:30:00",
48+
"updatedAt": "2025-09-22T10:30:00"
49+
}
50+
}
51+
""")
52+
)
53+
),
54+
@ApiResponse(
55+
responseCode = "400",
56+
description = "잘못된 요청 (필드 누락 등)",
57+
content = @Content(
58+
mediaType = "application/json",
59+
examples = @ExampleObject(value = """
60+
{
61+
"success": false,
62+
"code": "COMMON_400",
63+
"message": "잘못된 요청입니다.",
64+
"data": null
65+
}
66+
""")
67+
)
68+
),
69+
@ApiResponse(
70+
responseCode = "401",
71+
description = "인증 실패 (토큰 없음/잘못됨/만료)",
72+
content = @Content(
73+
mediaType = "application/json",
74+
examples = {
75+
@ExampleObject(name = "토큰 없음", value = """
76+
{
77+
"success": false,
78+
"code": "AUTH_001",
79+
"message": "인증이 필요합니다.",
80+
"data": null
81+
}
82+
"""),
83+
@ExampleObject(name = "잘못된 토큰", value = """
84+
{
85+
"success": false,
86+
"code": "AUTH_002",
87+
"message": "유효하지 않은 액세스 토큰입니다.",
88+
"data": null
89+
}
90+
"""),
91+
@ExampleObject(name = "만료된 토큰", value = """
92+
{
93+
"success": false,
94+
"code": "AUTH_004",
95+
"message": "만료된 액세스 토큰입니다.",
96+
"data": null
97+
}
98+
""")
99+
}
100+
)
101+
),
102+
@ApiResponse(
103+
responseCode = "404",
104+
description = "존재하지 않는 사용자 또는 카테고리",
105+
content = @Content(
106+
mediaType = "application/json",
107+
examples = {
108+
@ExampleObject(name = "존재하지 않는 사용자", value = """
109+
{
110+
"success": false,
111+
"code": "USER_001",
112+
"message": "존재하지 않는 사용자입니다.",
113+
"data": null
114+
}
115+
"""),
116+
@ExampleObject(name = "존재하지 않는 카테고리", value = """
117+
{
118+
"success": false,
119+
"code": "POST_003",
120+
"message": "존재하지 않는 카테고리입니다.",
121+
"data": null
122+
}
123+
""")
124+
}
125+
)
126+
),
127+
@ApiResponse(
128+
responseCode = "500",
129+
description = "서버 내부 오류",
130+
content = @Content(
131+
mediaType = "application/json",
132+
examples = @ExampleObject(value = """
133+
{
134+
"success": false,
135+
"code": "COMMON_500",
136+
"message": "서버 오류가 발생했습니다.",
137+
"data": null
138+
}
139+
""")
140+
)
141+
)
142+
})
143+
ResponseEntity<RsData<PostResponse>> createPost(
144+
@RequestBody PostRequest request,
145+
@AuthenticationPrincipal CustomUserDetails user
146+
);
147+
}

0 commit comments

Comments
 (0)