Skip to content

Commit a7a3186

Browse files
joyewon0705joyewon0705
committed
Docs: Swagger 문서 작성
1 parent a486b08 commit a7a3186

File tree

1 file changed

+152
-2
lines changed

1 file changed

+152
-2
lines changed

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

Lines changed: 152 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
package com.back.domain.board.controller;
22

3-
import com.back.domain.board.dto.PostRequest;
4-
import com.back.domain.board.dto.PostResponse;
3+
import com.back.domain.board.dto.*;
54
import com.back.global.common.dto.RsData;
65
import com.back.global.security.user.CustomUserDetails;
76
import io.swagger.v3.oas.annotations.Operation;
@@ -10,9 +9,13 @@
109
import io.swagger.v3.oas.annotations.responses.ApiResponse;
1110
import io.swagger.v3.oas.annotations.responses.ApiResponses;
1211
import io.swagger.v3.oas.annotations.tags.Tag;
12+
import org.springframework.data.domain.Pageable;
13+
import org.springframework.data.web.PageableDefault;
1314
import org.springframework.http.ResponseEntity;
1415
import org.springframework.security.core.annotation.AuthenticationPrincipal;
16+
import org.springframework.web.bind.annotation.PathVariable;
1517
import org.springframework.web.bind.annotation.RequestBody;
18+
import org.springframework.web.bind.annotation.RequestParam;
1619

1720
@Tag(name = "Post API", description = "게시글 관련 API")
1821
public interface PostControllerDocs {
@@ -144,4 +147,151 @@ ResponseEntity<RsData<PostResponse>> createPost(
144147
@RequestBody PostRequest request,
145148
@AuthenticationPrincipal CustomUserDetails user
146149
);
150+
151+
@Operation(
152+
summary = "게시글 목록 조회",
153+
description = "모든 사용자가 게시글 목록을 조회할 수 있습니다. (로그인 불필요)"
154+
)
155+
@ApiResponses({
156+
@ApiResponse(
157+
responseCode = "200",
158+
description = "게시글 목록 조회 성공",
159+
content = @Content(
160+
mediaType = "application/json",
161+
examples = @ExampleObject(value = """
162+
{
163+
"success": true,
164+
"code": "SUCCESS_200",
165+
"message": "게시글 목록이 조회되었습니다.",
166+
"data": {
167+
"items": [
168+
{
169+
"postId": 1,
170+
"author": { "id": 10, "nickname": "홍길동" },
171+
"title": "첫 글",
172+
"categories": [{ "id": 1, "name": "공지사항" }],
173+
"likeCount": 5,
174+
"bookmarkCount": 2,
175+
"commentCount": 3,
176+
"createdAt": "2025-09-30T10:15:30",
177+
"updatedAt": "2025-09-30T10:20:00"
178+
}
179+
],
180+
"page": 0,
181+
"size": 10,
182+
"totalElements": 25,
183+
"totalPages": 3,
184+
"last": false
185+
}
186+
}
187+
""")
188+
)
189+
),
190+
@ApiResponse(
191+
responseCode = "400",
192+
description = "잘못된 요청 (페이징 파라미터 오류 등)",
193+
content = @Content(
194+
mediaType = "application/json",
195+
examples = @ExampleObject(value = """
196+
{
197+
"success": false,
198+
"code": "COMMON_400",
199+
"message": "잘못된 요청입니다.",
200+
"data": null
201+
}
202+
""")
203+
)
204+
),
205+
@ApiResponse(
206+
responseCode = "500",
207+
description = "서버 내부 오류",
208+
content = @Content(
209+
mediaType = "application/json",
210+
examples = @ExampleObject(value = """
211+
{
212+
"success": false,
213+
"code": "COMMON_500",
214+
"message": "서버 오류가 발생했습니다.",
215+
"data": null
216+
}
217+
""")
218+
)
219+
)
220+
})
221+
ResponseEntity<RsData<PageResponse<PostListResponse>>> getPosts(
222+
@PageableDefault(sort = "createdAt") Pageable pageable,
223+
@RequestParam(required = false) String keyword,
224+
@RequestParam(required = false) String searchType,
225+
@RequestParam(required = false) Long categoryId
226+
);
227+
228+
229+
@Operation(
230+
summary = "게시글 단건 조회",
231+
description = "모든 사용자가 특정 게시글의 상세 정보를 조회할 수 있습니다. (로그인 불필요)"
232+
)
233+
@ApiResponses({
234+
@ApiResponse(
235+
responseCode = "200",
236+
description = "게시글 단건 조회 성공",
237+
content = @Content(
238+
mediaType = "application/json",
239+
examples = @ExampleObject(value = """
240+
{
241+
"success": true,
242+
"code": "SUCCESS_200",
243+
"message": "게시글이 조회되었습니다.",
244+
"data": {
245+
"postId": 101,
246+
"author": { "id": 5, "nickname": "홍길동" },
247+
"title": "첫 번째 게시글",
248+
"content": "안녕하세요, 첫 글입니다!",
249+
"categories": [
250+
{ "id": 1, "name": "공지사항" },
251+
{ "id": 2, "name": "자유게시판" }
252+
],
253+
"likeCount": 10,
254+
"bookmarkCount": 2,
255+
"commentCount": 3,
256+
"createdAt": "2025-09-22T10:30:00",
257+
"updatedAt": "2025-09-22T10:30:00"
258+
}
259+
}
260+
""")
261+
)
262+
),
263+
@ApiResponse(
264+
responseCode = "404",
265+
description = "존재하지 않는 게시글",
266+
content = @Content(
267+
mediaType = "application/json",
268+
examples = @ExampleObject(value = """
269+
{
270+
"success": false,
271+
"code": "POST_001",
272+
"message": "존재하지 않는 게시글입니다.",
273+
"data": null
274+
}
275+
""")
276+
)
277+
),
278+
@ApiResponse(
279+
responseCode = "500",
280+
description = "서버 내부 오류",
281+
content = @Content(
282+
mediaType = "application/json",
283+
examples = @ExampleObject(value = """
284+
{
285+
"success": false,
286+
"code": "COMMON_500",
287+
"message": "서버 오류가 발생했습니다.",
288+
"data": null
289+
}
290+
""")
291+
)
292+
)
293+
})
294+
ResponseEntity<RsData<PostDetailResponse>> getPost(
295+
@PathVariable Long postId
296+
);
147297
}

0 commit comments

Comments
 (0)