From 7b1cce87065832868b7b18b3f3a34f88a5d2ff02 Mon Sep 17 00:00:00 2001 From: rlarlgnszx Date: Sun, 14 Jul 2024 22:42:37 +0900 Subject: [PATCH 1/2] =?UTF-8?q?[docs]=20=EA=B4=91=EA=B3=A0=20swagger=20?= =?UTF-8?q?=EC=9E=91=EC=84=B1-=20=20#94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../advertisment/api/AdvertismentApi.java | 94 +++++++++++++++++++ .../api/AdvertismentController.java | 6 +- 2 files changed, 96 insertions(+), 4 deletions(-) create mode 100644 dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java diff --git a/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java b/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java new file mode 100644 index 00000000..fd495bce --- /dev/null +++ b/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java @@ -0,0 +1,94 @@ +package org.dateroad.advertisment.api; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.security.SecurityRequirement; +import io.swagger.v3.oas.annotations.tags.Tag; +import org.dateroad.advertisment.dto.response.AdvGetAllRes; +import org.dateroad.advertisment.dto.response.AdvGetDetailRes; +import org.dateroad.auth.argumentresolve.UserId; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.PathVariable; + +@Tag(name = "광고 관련 API") +@SecurityRequirement(name = "Authorization") +public interface AdvertismentApi { + @Operation( + summary = "광고 전체 조회 API", + responses = { + @ApiResponse( + responseCode = "200", + content = @Content(schema = @Schema(implementation = AdvGetAllRes.class)), + description = "요청이 성공했습니다."), + @ApiResponse( + responseCode = "400", + description = "잘못된 요청입니다.", + content = @Content), + @ApiResponse( + responseCode = "401", + description = "액세스 토큰의 형식이 올바르지 않습니다. Bearer 타입을 확인해 주세요.", + content = @Content), + @ApiResponse( + responseCode = "401", + description = "액세스 토큰의 값이 올바르지 않습니다.", + content = @Content), + @ApiResponse( + responseCode = "401", + description = "액세스 토큰이 만료되었습니다. 재발급 받아주세요.", + content = @Content), + @ApiResponse( + responseCode = "405", + description = "잘못된 HTTP method 요청입니다.", + content = @Content), + @ApiResponse( + responseCode = "500", + description = "서버 내부 오류입니다.", + content = @Content)}) + ResponseEntity getAllAdvertisments(); + @Operation( + summary = "광고 상세 조회 API", + responses = { + @ApiResponse( + responseCode = "200", + description = "요청이 성공했습니다.", + content = @Content(schema = @Schema(implementation = AdvGetDetailRes.class))), + @ApiResponse( + responseCode = "400", + description = "잘못된 요청입니다.", + content = @Content), + @ApiResponse( + responseCode = "400", + description = "유효하지 않은 요청 파라미터 값입니다.", + content = @Content), + @ApiResponse( + responseCode = "401", + description = "액세스 토큰의 형식이 올바르지 않습니다. Bearer 타입을 확인해 주세요.", + content = @Content), + @ApiResponse( + responseCode = "401", + description = "액세스 토큰의 값이 올바르지 않습니다.", + content = @Content), + @ApiResponse( + responseCode = "401", + description = "액세스 토큰이 만료되었습니다. 재발급 받아주세요.", + content = @Content), + + @ApiResponse( + responseCode = "404", + description = "존재하지 않는 광고입니다.", + content = @Content), + @ApiResponse( + responseCode = "405", + description = "잘못된 HTTP method 요청입니다.", + content = @Content), + @ApiResponse( + responseCode = "500", + description = "서버 내부 오류입니다.", + content = @Content)}) + ResponseEntity getAdvertismentsDetail( + @Parameter(hidden = true) final @PathVariable Long advId + ); +} diff --git a/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentController.java b/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentController.java index 1cd47c94..fa13f43a 100644 --- a/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentController.java +++ b/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentController.java @@ -4,18 +4,16 @@ import org.dateroad.advertisment.dto.response.AdvGetAllRes; import org.dateroad.advertisment.dto.response.AdvGetDetailRes; import org.dateroad.advertisment.service.AdvertismentService; -import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; -import org.springframework.web.bind.annotation.RequestHeader; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequiredArgsConstructor @RequestMapping("/api/v1/advertisments") -public class AdvertismentController { +public class AdvertismentController implements AdvertismentApi { private final AdvertismentService advertismentService; @GetMapping @@ -24,7 +22,7 @@ public ResponseEntity getAllAdvertisments(){ } @GetMapping("{advId}") - public ResponseEntity getAllAdvertisments( + public ResponseEntity getAdvertismentsDetail( final @PathVariable Long advId ){ return ResponseEntity.ok(advertismentService.getAdvertismentsDetail(advId)); From 5f3d6881ec3441708db78a4cad1e72c1ab3d5ebb Mon Sep 17 00:00:00 2001 From: rlarlgnszx Date: Sun, 14 Jul 2024 23:39:31 +0900 Subject: [PATCH 2/2] =?UTF-8?q?[docs]=20=EA=B4=91=EA=B3=A0=20=EC=A1=B0?= =?UTF-8?q?=ED=9A=8C=20API=20=EB=AA=85=EC=84=B8=20=EC=98=88=EC=8B=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=20-=20#94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../advertisment/api/AdvertismentApi.java | 61 +++++++++++++++++-- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java b/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java index fd495bce..f79121db 100644 --- a/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java +++ b/dateroad-api/src/main/java/org/dateroad/advertisment/api/AdvertismentApi.java @@ -3,6 +3,7 @@ import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.security.SecurityRequirement; @@ -21,8 +22,37 @@ public interface AdvertismentApi { responses = { @ApiResponse( responseCode = "200", - content = @Content(schema = @Schema(implementation = AdvGetAllRes.class)), - description = "요청이 성공했습니다."), + content = @Content( + schema = @Schema(implementation = AdvGetAllRes.class), + examples = @ExampleObject(value = """ + { + "advertismentDtoResList": [ + { + "advertismentId": 1, + "thumbnail": "http://example.com/thumbnail1.jpg", + "title": "광고 제목 1", + }, + { + "advertismentId": 2, + "thumbnail": "http://example.com/thumbnail2.jpg", + "title": "광고 제목 2", + }, + { + "advertismentId": 3, + "thumbnail": "http://example.com/thumbnail2.jpg", + "title": "광고 제목 3", + }, + { + "advertismentId": 4, + "thumbnail": "http://example.com/thumbnail2.jpg", + "title": "광고 제목 4", + } + ] + } + """) + ), + description = "요청이 성공했습니다." + ), @ApiResponse( responseCode = "400", description = "잘못된 요청입니다.", @@ -48,13 +78,34 @@ public interface AdvertismentApi { description = "서버 내부 오류입니다.", content = @Content)}) ResponseEntity getAllAdvertisments(); + @Operation( summary = "광고 상세 조회 API", responses = { @ApiResponse( responseCode = "200", - description = "요청이 성공했습니다.", - content = @Content(schema = @Schema(implementation = AdvGetDetailRes.class))), + content = @Content( + schema = @Schema(implementation = AdvGetDetailRes.class), + examples = @ExampleObject(value = """ + { + "images": [ + { + "imagesUrl": "http://example.com/image1.jpg", + "sequence": 1 + }, + { + "imagesUrl": "http://example.com/image2.jpg", + "sequence": 2 + } + ], + "title": "광고 제목", + "createAt": "2023.07.14", + "description": "광고 설명" + } + """) + ), + description = "요청이 성공했습니다." + ), @ApiResponse( responseCode = "400", description = "잘못된 요청입니다.", @@ -89,6 +140,6 @@ public interface AdvertismentApi { description = "서버 내부 오류입니다.", content = @Content)}) ResponseEntity getAdvertismentsDetail( - @Parameter(hidden = true) final @PathVariable Long advId + @Parameter(required = true) final @PathVariable Long advId ); }