Skip to content

Commit 5d1e84d

Browse files
Hyeonjun0527Hyeonjun0527
authored
btsk-123: 200요청에 대한 example object 추가 (#159)
* docs: 200요청에 대한 example object 추가 * refactor: 코드스타일
1 parent 1cc5263 commit 5d1e84d

21 files changed

+443
-22
lines changed

‎src/main/java/kr/it/pullit/modules/auth/web/apidocs/ReissueTokenApiDocs.java‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.ExampleObject;
56
import io.swagger.v3.oas.annotations.media.Schema;
67
import io.swagger.v3.oas.annotations.responses.ApiResponse;
78
import java.lang.annotation.ElementType;
@@ -18,5 +19,16 @@
1819
@ApiResponse(
1920
responseCode = "200",
2021
description = "액세스 토큰 재발급 성공",
21-
content = @Content(schema = @Schema(implementation = AccessTokenResponse.class)))
22+
content =
23+
@Content(
24+
schema = @Schema(implementation = AccessTokenResponse.class),
25+
examples =
26+
@ExampleObject(
27+
name = "토큰 재발급 성공",
28+
value =
29+
"""
30+
{
31+
"accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOHAiOjE2MTYyMjc4NDJ9"
32+
}
33+
""")))
2234
public @interface ReissueTokenApiDocs {}

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/GetCommonFolderApiDocs.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.ExampleObject;
56
import io.swagger.v3.oas.annotations.media.Schema;
67
import io.swagger.v3.oas.annotations.responses.ApiResponse;
78
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
@@ -34,5 +35,18 @@
3435
content =
3536
@Content(
3637
mediaType = "application/json",
37-
schema = @Schema(implementation = CommonFolderResponse.class)))
38+
schema = @Schema(implementation = CommonFolderResponse.class),
39+
examples =
40+
@ExampleObject(
41+
name = "공통 폴더 조회 예시",
42+
value =
43+
"""
44+
{
45+
"id": 1,
46+
"name": "Java 기초",
47+
"type": "QUESTION_SET",
48+
"scope": "ALL",
49+
"sortOrder": 1
50+
}
51+
""")))
3852
public @interface GetCommonFolderApiDocs {}

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/GetCommonFoldersApiDocs.java‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.ArraySchema;
55
import io.swagger.v3.oas.annotations.media.Content;
6+
import io.swagger.v3.oas.annotations.media.ExampleObject;
67
import io.swagger.v3.oas.annotations.media.Schema;
78
import io.swagger.v3.oas.annotations.responses.ApiResponse;
89
import io.swagger.v3.oas.annotations.responses.ApiResponses;
@@ -40,6 +41,28 @@
4041
@Content(
4142
mediaType = "application/json",
4243
array =
43-
@ArraySchema(schema = @Schema(implementation = CommonFolderResponse.class))))
44+
@ArraySchema(schema = @Schema(implementation = CommonFolderResponse.class)),
45+
examples =
46+
@ExampleObject(
47+
name = "공통 폴더 목록 예시",
48+
value =
49+
"""
50+
[
51+
{
52+
"id": 1,
53+
"name": "기본 폴더",
54+
"type": "QUESTION_SET",
55+
"scope": "ALL",
56+
"sortOrder": 0
57+
},
58+
{
59+
"id": 2,
60+
"name": "자주 쓰는 문제집",
61+
"type": "QUESTION_SET",
62+
"scope": "ALL",
63+
"sortOrder": 1
64+
}
65+
]
66+
""")))
4467
})
4568
public @interface GetCommonFoldersApiDocs {}

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/GetFolderByIdApiDocs.java‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,20 @@
4040
content =
4141
@Content(
4242
mediaType = "application/json",
43-
schema = @Schema(implementation = CommonFolderResponse.class))),
43+
schema = @Schema(implementation = CommonFolderResponse.class),
44+
examples =
45+
@ExampleObject(
46+
name = "사용자 폴더 조회 예시",
47+
value =
48+
"""
49+
{
50+
"id": 101,
51+
"name": "JPA 심화",
52+
"type": "QUESTION_SET",
53+
"scope": "CUSTOM",
54+
"sortOrder": 1
55+
}
56+
"""))),
4457
@ApiResponse(
4558
responseCode = "404",
4659
description = "존재하지 않거나 권한이 없는 폴더",

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/GetFolderDeleteWarningApiDocs.java‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,16 @@
4040
content =
4141
@Content(
4242
mediaType = "application/json",
43-
schema = @Schema(implementation = FolderDeleteWarningResponse.class))),
43+
schema = @Schema(implementation = FolderDeleteWarningResponse.class),
44+
examples =
45+
@ExampleObject(
46+
name = "삭제 경고 응답",
47+
value =
48+
"""
49+
{
50+
"questionSetCount": 5
51+
}
52+
"""))),
4453
@ApiResponse(
4554
responseCode = "404",
4655
description = "존재하지 않거나 권한이 없는 폴더",

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/GetFoldersApiDocs.java‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.ExampleObject;
56
import io.swagger.v3.oas.annotations.media.Schema;
67
import io.swagger.v3.oas.annotations.responses.ApiResponse;
78
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
@@ -33,5 +34,27 @@
3334
content =
3435
@Content(
3536
mediaType = "application/json",
36-
schema = @Schema(implementation = CommonFolderResponse.class, type = "array")))
37+
schema = @Schema(implementation = CommonFolderResponse.class, type = "array"),
38+
examples =
39+
@ExampleObject(
40+
name = "내 폴더 목록 예시",
41+
value =
42+
"""
43+
[
44+
{
45+
"id": 101,
46+
"name": "JPA 심화",
47+
"type": "QUESTION_SET",
48+
"scope": "CUSTOM",
49+
"sortOrder": 1
50+
},
51+
{
52+
"id": 102,
53+
"name": "Spring Core",
54+
"type": "QUESTION_SET",
55+
"scope": "CUSTOM",
56+
"sortOrder": 2
57+
}
58+
]
59+
""")))
3760
public @interface GetFoldersApiDocs {}

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/UpdateCommonFolderApiDocs.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.ExampleObject;
56
import io.swagger.v3.oas.annotations.media.Schema;
67
import io.swagger.v3.oas.annotations.parameters.RequestBody;
78
import io.swagger.v3.oas.annotations.responses.ApiResponse;
@@ -34,5 +35,18 @@
3435
content =
3536
@Content(
3637
mediaType = "application/json",
37-
schema = @Schema(implementation = CommonFolderResponse.class)))
38+
schema = @Schema(implementation = CommonFolderResponse.class),
39+
examples =
40+
@ExampleObject(
41+
name = "폴더 수정 응답 예시",
42+
value =
43+
"""
44+
{
45+
"id": 5,
46+
"name": "심화 학습",
47+
"type": "QUESTION_SET",
48+
"scope": "ALL",
49+
"sortOrder": 0
50+
}
51+
""")))
3852
public @interface UpdateCommonFolderApiDocs {}

‎src/main/java/kr/it/pullit/modules/commonfolder/web/apidocs/UpdateFolderApiDocs.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.ExampleObject;
56
import io.swagger.v3.oas.annotations.media.Schema;
67
import io.swagger.v3.oas.annotations.responses.ApiResponse;
78
import io.swagger.v3.oas.annotations.responses.ApiResponses;
@@ -39,7 +40,20 @@
3940
content =
4041
@Content(
4142
mediaType = "application/json",
42-
schema = @Schema(implementation = CommonFolderResponse.class))),
43+
schema = @Schema(implementation = CommonFolderResponse.class),
44+
examples =
45+
@ExampleObject(
46+
name = "폴더 정보 수정 예시",
47+
value =
48+
"""
49+
{
50+
"id": 101,
51+
"name": "Spring 심화",
52+
"type": "QUESTION_SET",
53+
"scope": "CUSTOM",
54+
"sortOrder": 1
55+
}
56+
"""))),
4357
@ApiResponse(
4458
responseCode = "400",
4559
description = "유효하지 않은 입력값입니다.",

‎src/main/java/kr/it/pullit/modules/learningsource/source/web/apidocs/GenerateUploadUrlApiDocs.java‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import io.swagger.v3.oas.annotations.Operation;
44
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.ExampleObject;
56
import io.swagger.v3.oas.annotations.media.Schema;
67
import io.swagger.v3.oas.annotations.responses.ApiResponse;
78
import io.swagger.v3.oas.annotations.responses.ApiResponses;
@@ -35,7 +36,23 @@
3536
@ApiResponse(
3637
responseCode = "200",
3738
description = "URL 생성 성공",
38-
content = @Content(schema = @Schema(implementation = SourceUploadResponse.class))),
39+
content =
40+
@Content(
41+
schema = @Schema(implementation = SourceUploadResponse.class),
42+
examples =
43+
@ExampleObject(
44+
name = "S3 Presigned URL 생성 응답",
45+
value =
46+
"""
47+
{
48+
"uploadUrl": "https://s3.ap-northeast-2.amazonaws.com/pullit/source/1/2025/11/10/...",
49+
"filePath": "source/1/2025/11/10/generated-uuid-filename.pdf",
50+
"originalName": "my-document.pdf",
51+
"contentType": "application/pdf",
52+
"fileSizeBytes": 204800,
53+
"uploadId": "18c9c8be-e5d4-4c37-b0c4-ccf3c4fc4b65"
54+
}
55+
"""))),
3956
@ApiResponse(
4057
responseCode = "400",
4158
description = "파일 크기 제한 초과",

‎src/main/java/kr/it/pullit/modules/learningsource/source/web/apidocs/GetMySourcesApiDocs.java‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,37 @@
3838
content =
3939
@Content(
4040
mediaType = "application/json",
41-
array = @ArraySchema(schema = @Schema(implementation = SourceResponse.class)))),
41+
array = @ArraySchema(schema = @Schema(implementation = SourceResponse.class)),
42+
examples =
43+
@ExampleObject(
44+
name = "학습 소스 목록 조회 예시",
45+
value =
46+
"""
47+
[
48+
{
49+
"id": 1,
50+
"originalName": "orientation.pdf",
51+
"sourceFolderName": "기본 폴더",
52+
"status": "READY",
53+
"questionSetCount": 2,
54+
"pageCount": 15,
55+
"fileSizeBytes": 204800,
56+
"createdAt": "2025-01-01",
57+
"recentQuestionGeneratedAt": "2025-01-05"
58+
},
59+
{
60+
"id": 2,
61+
"originalName": "jpa-programming.pdf",
62+
"sourceFolderName": "CS 스터디",
63+
"status": "PROCESSING",
64+
"questionSetCount": 0,
65+
"pageCount": 350,
66+
"fileSizeBytes": 1024500,
67+
"createdAt": "2025-02-10",
68+
"recentQuestionGeneratedAt": null
69+
}
70+
]
71+
"""))),
4272
@ApiResponse(
4373
responseCode = "400",
4474
description = "요청 정보가 유효하지 않음",

0 commit comments

Comments
 (0)