#2 - Feat: Add Area Code Search rest docs

route-master · Aug 4, 2023 · 0cf763f · 0cf763f
1 parent 3bf248c
commit 0cf763f
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 8 deletions.
diff --git a/...utemaster/api/total/domain/attraction/controller/AttractionUtilsSearchRestController.java b/...utemaster/api/total/domain/attraction/controller/AttractionUtilsSearchRestController.java
@@ -86,11 +86,43 @@ public ResponseEntity<Mono<CategorySearchResponse>> searchCategory(
         return new ResponseEntity<>(response, HttpStatus.OK);
     }
 
+    @Operation(
+            summary = "지역 코드, 시군구 코드 조회",
+            description = "지역 코드, 시군구 코드 목록을 조회하는 기능",
+            tags = {
+                    "attraction-utils"
+            }
+    )
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description= "Success Response",
+                    content = @Content(
+                            mediaType = "application/json",
+                            schema = @Schema(implementation = AreaCodeSearchResponse.class)
+                    )
+            )
+    })
     @GetMapping("/areaCode")
     ResponseEntity<Mono<AreaCodeSearchResponse>> searchAreaCode(
-            @RequestParam(required = false) Integer numOfRows,
-            @RequestParam(required = false) Integer pageNo,
-            @RequestParam(required = false) Integer areaCode
+            @Parameter(
+                    description = "한 페이지 결과 수",
+                    example = "10",
+                    schema = @Schema(
+                            defaultValue = "10"
+                    )
+            ) @RequestParam(required = false) Integer numOfRows,
+            @Parameter(
+                    description = "페이지 번호",
+                    example = "1",
+                    schema = @Schema(
+                            defaultValue = "1"
+                    )
+            ) @RequestParam(required = false) Integer pageNo,
+            @Parameter(
+                    description = "지역 코드",
+                    example = "1"
+            ) @RequestParam(required = false) Integer areaCode
     ) {
         Mono<AreaCodeSearchResponse> response = service.searchAreaCode(numOfRows, pageNo, areaCode);
         return new ResponseEntity<>(response, HttpStatus.OK);

diff --git a/src/main/java/org/routemaster/api/total/domain/attraction/data/utils/AreaCodeItem.java b/src/main/java/org/routemaster/api/total/domain/attraction/data/utils/AreaCodeItem.java
@@ -1,6 +1,7 @@
 package org.routemaster.api.total.domain.attraction.data.utils;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.*;
 import lombok.extern.slf4j.Slf4j;
 
@@ -12,9 +13,18 @@
 @ToString
 public class AreaCodeItem {
 
-    private String areaCode;
-    private String areaName;
-    private Integer rowNumber;
+    @Schema(
+            description = "지역 코드 또는 시군구 코드",
+            example = "1"
+    ) private String areaCode;
+    @Schema(
+            description = "지역명 또는 시군구명",
+            example = "서울"
+    ) private String areaName;
+    @Schema(
+            description = "일련번호",
+            example = "1"
+    ) private Integer rowNumber;
 
     public static final class AreaCodeItemBuilder {
         public AreaCodeItemBuilder buildFromJsonNode(JsonNode jsonNode) {

diff --git a/...n/java/org/routemaster/api/total/domain/attraction/data/utils/AreaCodeSearchResponse.java b/...n/java/org/routemaster/api/total/domain/attraction/data/utils/AreaCodeSearchResponse.java
@@ -1,6 +1,7 @@
 package org.routemaster.api.total.domain.attraction.data.utils;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.*;
 import lombok.extern.slf4j.Slf4j;
 import org.routemaster.api.total.domain.attraction.data.TourApiResponseHeader;
@@ -16,8 +17,12 @@
 @ToString
 public class AreaCodeSearchResponse {
 
-    private TourApiResponseHeader header;
-    private List<AreaCodeItem> areaCodeItems;
+    @Schema(
+            description = "API 호출 결과 헤더"
+    ) private TourApiResponseHeader header;
+    @Schema(
+            description = "지역 코드 검색 결과"
+    ) private List<AreaCodeItem> areaCodeItems;
 
     public static class AreaCodeSearchResponseBuilder {
         public AreaCodeSearchResponseBuilder buildFromJsonNode(JsonNode jsonNode) {