Skip to content

Commit afbf45f

Browse files
joyewon0705joyewon0705
committed
Docs: Swagger 문서 작성
1 parent 3fcb423 commit afbf45f

File tree

2 files changed

+189
-1
lines changed

2 files changed

+189
-1
lines changed

‎src/main/java/com/back/domain/board/post/controller/PostCategoryController.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
@RestController
1818
@RequestMapping("/api/posts/categories")
1919
@RequiredArgsConstructor
20-
public class PostCategoryController {
20+
public class PostCategoryController implements PostCategoryControllerDocs {
2121
private final PostCategoryService postCategoryService;
2222

2323
// 카테고리 생성

‎src/main/java/com/back/domain/board/post/controller/PostCategoryControllerDocs.java‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
package com.back.domain.board.post.controller;
2+
3+
import com.back.domain.board.post.dto.CategoryRequest;
4+
import com.back.domain.board.post.dto.CategoryResponse;
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+
import java.util.List;
18+
19+
@Tag(name = "Category API", description = "게시글 카테고리 관련 API")
20+
public interface PostCategoryControllerDocs {
21+
22+
@Operation(
23+
summary = "카테고리 생성",
24+
description = "로그인한 사용자가 새 카테고리를 등록합니다."
25+
)
26+
@ApiResponses({
27+
@ApiResponse(
28+
responseCode = "201",
29+
description = "카테고리 생성 성공",
30+
content = @Content(
31+
mediaType = "application/json",
32+
examples = @ExampleObject(value = """
33+
{
34+
"success": true,
35+
"code": "SUCCESS_201",
36+
"message": "카테고리가 생성되었습니다.",
37+
"data": {
38+
"id": 80,
39+
"name": "수학 II",
40+
"type": "SUBJECT"
41+
}
42+
}
43+
""")
44+
)
45+
),
46+
@ApiResponse(
47+
responseCode = "400",
48+
description = "잘못된 요청 (필드 누락 등)",
49+
content = @Content(
50+
mediaType = "application/json",
51+
examples = @ExampleObject(value = """
52+
{
53+
"success": false,
54+
"code": "COMMON_400",
55+
"message": "잘못된 요청입니다.",
56+
"data": null
57+
}
58+
""")
59+
)
60+
),
61+
@ApiResponse(
62+
responseCode = "401",
63+
description = "인증 실패 (Access Token 없음/만료/잘못됨)",
64+
content = @Content(
65+
mediaType = "application/json",
66+
examples = {
67+
@ExampleObject(name = "토큰 없음", value = """
68+
{
69+
"success": false,
70+
"code": "AUTH_001",
71+
"message": "인증이 필요합니다.",
72+
"data": null
73+
}
74+
"""),
75+
@ExampleObject(name = "유효하지 않은 토큰", value = """
76+
{
77+
"success": false,
78+
"code": "AUTH_002",
79+
"message": "유효하지 않은 액세스 토큰입니다.",
80+
"data": null
81+
}
82+
"""),
83+
@ExampleObject(name = "만료된 토큰", value = """
84+
{
85+
"success": false,
86+
"code": "AUTH_004",
87+
"message": "만료된 액세스 토큰입니다.",
88+
"data": null
89+
}
90+
""")
91+
}
92+
)
93+
),
94+
@ApiResponse(
95+
responseCode = "404",
96+
description = "존재하지 않는 사용자",
97+
content = @Content(
98+
mediaType = "application/json",
99+
examples = @ExampleObject(value = """
100+
{
101+
"success": false,
102+
"code": "USER_001",
103+
"message": "존재하지 않는 사용자입니다.",
104+
"data": null
105+
}
106+
""")
107+
)
108+
),
109+
@ApiResponse(
110+
responseCode = "409",
111+
description = "이미 존재하는 카테고리 이름",
112+
content = @Content(
113+
mediaType = "application/json",
114+
examples = @ExampleObject(value = """
115+
{
116+
"success": false,
117+
"code": "POST_004",
118+
"message": "이미 존재하는 카테고리입니다.",
119+
"data": null
120+
}
121+
""")
122+
)
123+
),
124+
@ApiResponse(
125+
responseCode = "500",
126+
description = "서버 내부 오류",
127+
content = @Content(
128+
mediaType = "application/json",
129+
examples = @ExampleObject(value = """
130+
{
131+
"success": false,
132+
"code": "COMMON_500",
133+
"message": "서버 오류가 발생했습니다.",
134+
"data": null
135+
}
136+
""")
137+
)
138+
)
139+
})
140+
ResponseEntity<RsData<CategoryResponse>> createCategory(
141+
@RequestBody CategoryRequest request,
142+
@AuthenticationPrincipal CustomUserDetails user
143+
);
144+
145+
@Operation(
146+
summary = "카테고리 전체 조회",
147+
description = "현재 등록된 모든 카테고리 목록을 조회합니다."
148+
)
149+
@ApiResponses({
150+
@ApiResponse(
151+
responseCode = "200",
152+
description = "카테고리 목록 조회 성공",
153+
content = @Content(
154+
mediaType = "application/json",
155+
examples = @ExampleObject(value = """
156+
{
157+
"success": true,
158+
"code": "SUCCESS_200",
159+
"message": "카테고리 목록이 조회되었습니다.",
160+
"data": [
161+
{ "id": 1, "name": "프론트엔드", "type": "SUBJECT" },
162+
{ "id": 2, "name": "백엔드", "type": "SUBJECT" },
163+
{ "id": 3, "name": "CS", "type": "SUBJECT" },
164+
{ "id": 74, "name": "중학생", "type": "DEMOGRAPHIC" },
165+
{ "id": 78, "name": "2~4명", "type": "GROUP_SIZE" }
166+
]
167+
}
168+
""")
169+
)
170+
),
171+
@ApiResponse(
172+
responseCode = "500",
173+
description = "서버 내부 오류",
174+
content = @Content(
175+
mediaType = "application/json",
176+
examples = @ExampleObject(value = """
177+
{
178+
"success": false,
179+
"code": "COMMON_500",
180+
"message": "서버 오류가 발생했습니다.",
181+
"data": null
182+
}
183+
""")
184+
)
185+
)
186+
})
187+
ResponseEntity<RsData<List<CategoryResponse>>> getAllCategories();
188+
}

0 commit comments

Comments
 (0)