refactor: swagger Tag & Operation 수정

dnd-side-project · Sep 2, 2024 · ee08f11 · ee08f11
1 parent 395ef70
commit ee08f11
Show file tree

Hide file tree

Showing 15 changed files with 87 additions and 18 deletions.
diff --git a/src/main/kotlin/dnd11th/blooming/api/config/SwaggerConfig.kt b/src/main/kotlin/dnd11th/blooming/api/config/SwaggerConfig.kt
@@ -22,7 +22,7 @@ import org.springframework.context.annotation.Configuration
 @Configuration
 class SwaggerConfig {
     companion object {
-        const val AUTHORIZATION = "bearerToken"
+        const val AUTHORIZATION = "AccessToken"
     }
 
     @Bean
@@ -68,7 +68,7 @@ class SwaggerConfig {
         return Info()
             .title("\uD83C\uDF40Blomming\uD83C\uDF40")
             .description("API 명세서입니다")
-            .title("v0.0.1")
+            .version("v1.0.0")
     }
 
     private fun generateErrorResponse(

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/home/HomeApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/home/HomeApi.kt
@@ -7,7 +7,7 @@ import io.swagger.v3.oas.annotations.media.Schema
 import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.tags.Tag
 
-@Tag(name = "2. [홈 화면]")
+@Tag(name = "3. [홈 화면]")
 interface HomeApi {
     @Operation(summary = "홈 화면의 정보들을 조회하는 API 입니다.")
     @ApiResponse(responseCode = "200", description = "홈 화면 조회 성공")

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/image/ImageApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/image/ImageApi.kt
@@ -13,7 +13,7 @@ import io.swagger.v3.oas.annotations.parameters.RequestBody
 import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.tags.Tag
 
-@Tag(name = "10. [이미지]")
+@Tag(name = "6. [이미지]")
 interface ImageApi {
     @Operation(summary = "이미지를 저장하는 API 입니다.")
     @ApiResponse(responseCode = "200", description = "이미지 저장 성공")

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/region/RegionApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/region/RegionApi.kt
@@ -0,0 +1,17 @@
+package dnd11th.blooming.api.controller.region
+
+import dnd11th.blooming.api.dto.region.RegionResponse
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.responses.ApiResponse
+import io.swagger.v3.oas.annotations.tags.Tag
+
+@Tag(name = "7. [지역]")
+interface RegionApi {
+    @Operation(summary = "지역을 검색하는 API 입니다.")
+    @ApiResponse(responseCode = "200", description = "지역 검색 성공")
+    fun findRegion(
+        @Parameter(description = "지역 이름", required = true)
+        name: String,
+    ): List<RegionResponse>
+}
diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/region/RegionController.kt b/src/main/kotlin/dnd11th/blooming/api/controller/region/RegionController.kt
@@ -11,9 +11,9 @@ import org.springframework.web.bind.annotation.RestController
 @RequestMapping("/api/v1/region")
 class RegionController(
     private val regionService: RegionService,
-) {
+) : RegionApi {
     @GetMapping
-    fun findRegion(
+    override fun findRegion(
         @RequestParam name: String,
     ): List<RegionResponse> {
         return regionService.findRegion(name)

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/user/DeviceTokenApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/user/DeviceTokenApi.kt
@@ -8,7 +8,7 @@ import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.tags.Tag
 import org.springframework.http.ResponseEntity
 
-@Tag(name = "1. [유저]")
+@Tag(name = "2. [유저]")
 interface DeviceTokenApi {
     @Operation(summary = "Device Token 등록 API")
     @ApiResponse(responseCode = "204", description = "Device Token 등록 성공")

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/user/TokenApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/user/TokenApi.kt
@@ -0,0 +1,14 @@
+package dnd11th.blooming.api.controller.user
+
+import dnd11th.blooming.api.dto.user.TokenRequest
+import dnd11th.blooming.api.dto.user.TokenResponse
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.responses.ApiResponse
+import io.swagger.v3.oas.annotations.tags.Tag
+
+@Tag(name = "1. [인증]")
+interface TokenApi {
+    @Operation(summary = "토큰 재발급 API 입니다.")
+    @ApiResponse(responseCode = "200", description = "토큰 재발급 성공")
+    fun reissueToken(tokenRequest: TokenRequest): TokenResponse
+}
diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/user/TokenController.kt b/src/main/kotlin/dnd11th/blooming/api/controller/user/TokenController.kt
@@ -12,9 +12,9 @@ import org.springframework.web.bind.annotation.RestController
 @RequestMapping("/api/v1/token")
 class TokenController(
     private val tokenService: TokenService,
-) {
+) : TokenApi {
     @PostMapping
-    fun reissueToken(
+    override fun reissueToken(
         @RequestBody tokenRequest: TokenRequest,
     ): TokenResponse {
         return tokenService.reissueToken(tokenRequest.refreshToken)

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/user/UserApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/user/UserApi.kt
@@ -1,16 +1,19 @@
 package dnd11th.blooming.api.controller.user
 
+import dnd11th.blooming.api.dto.user.MyProfileResponse
+import dnd11th.blooming.api.dto.user.MyProfileUpdateRequest
 import dnd11th.blooming.api.dto.user.TokenResponse
 import dnd11th.blooming.api.dto.user.UserRegisterRequest
 import dnd11th.blooming.domain.entity.user.RegisterClaims
+import dnd11th.blooming.domain.entity.user.User
 import io.swagger.v3.oas.annotations.Operation
 import io.swagger.v3.oas.annotations.Parameter
 import io.swagger.v3.oas.annotations.enums.ParameterIn
 import io.swagger.v3.oas.annotations.media.Schema
 import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.tags.Tag
 
-@Tag(name = "1. [유저]")
+@Tag(name = "2. [유저]")
 interface UserApi {
     @Operation(
         summary = "사용자 등록 API",
@@ -28,4 +31,31 @@ interface UserApi {
         @Schema(hidden = true) registerClaims: RegisterClaims,
         userRegisterRequest: UserRegisterRequest,
     ): TokenResponse
+
+    @Operation(summary = "마이페이지 API 입니다.")
+    @ApiResponse(responseCode = "200", description = "마이페이지 조회 성공")
+    fun findProfile(
+        @Schema(hidden = true) user: User,
+    ): MyProfileResponse
+
+    @Operation(summary = "닉네임 수정 API 입니다.")
+    @ApiResponse(responseCode = "204", description = "닉네임 수정 성공")
+    fun updateNickname(
+        @Schema(hidden = true) user: User,
+        updateNickName: MyProfileUpdateRequest.Nickname,
+    )
+
+    @Operation(summary = "알림 설정 수정 API 입니다.")
+    @ApiResponse(responseCode = "204", description = "알람 설정 여부 변경 성공")
+    fun updateAlarmStatus(
+        @Schema(hidden = true) user: User,
+        updateAlarmStatus: MyProfileUpdateRequest.AlarmStatus,
+    )
+
+    @Operation(summary = "알림 시간대 수정 API 입니다.")
+    @ApiResponse(responseCode = "204", description = "알람 사간대 변경 성공")
+    fun updateAlarmTime(
+        @Schema(hidden = true) user: User,
+        updateAlarmTime: MyProfileUpdateRequest.AlarmTime,
+    )
 }
diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/user/UserController.kt b/src/main/kotlin/dnd11th/blooming/api/controller/user/UserController.kt
@@ -40,15 +40,15 @@ class UserController(
 
     @Secured
     @GetMapping("/my")
-    fun findProfile(
+    override fun findProfile(
         @LoginUser user: User,
     ): MyProfileResponse {
         return userProfileService.findProfile(user)
     }
 
     @Secured
     @PatchMapping("/my/nickname")
-    fun updateNickname(
+    override fun updateNickname(
         @LoginUser user: User,
         @RequestBody updateNickName: MyProfileUpdateRequest.Nickname,
     ) {
@@ -57,7 +57,7 @@ class UserController(
 
     @Secured
     @PatchMapping("/my/alarm")
-    fun updateAlarmStatus(
+    override fun updateAlarmStatus(
         @LoginUser user: User,
         @RequestBody updateAlarmStatus: MyProfileUpdateRequest.AlarmStatus,
     ) {
@@ -66,7 +66,7 @@ class UserController(
 
     @Secured
     @PatchMapping("/my/alarm-time")
-    fun updateAlarmTime(
+    override fun updateAlarmTime(
         @LoginUser user: User,
         @RequestBody updateAlarmTime: MyProfileUpdateRequest.AlarmTime,
     ) {

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/user/UserLoginApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/user/UserLoginApi.kt
@@ -11,7 +11,7 @@ import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.responses.ApiResponses
 import io.swagger.v3.oas.annotations.tags.Tag
 
-@Tag(name = "1. [유저]")
+@Tag(name = "1. [인증]")
 interface UserLoginApi {
     @Operation(summary = "소셜 로그인 API")
     @ApiResponses(

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/weather/WeatherMessageApi.kt b/src/main/kotlin/dnd11th/blooming/api/controller/weather/WeatherMessageApi.kt
@@ -9,7 +9,7 @@ import io.swagger.v3.oas.annotations.media.Schema
 import io.swagger.v3.oas.annotations.responses.ApiResponse
 import io.swagger.v3.oas.annotations.tags.Tag
 
-@Tag(name = "5. [날씨 메시지]")
+@Tag(name = "8. [날씨 메시지]")
 interface WeatherMessageApi {
     @Operation(summary = "날씨 메시지를 조회하는 API 입니다.")
     @ApiResponse(responseCode = "200", description = "날씨 메시지 조회 성공")

diff --git a/src/main/kotlin/dnd11th/blooming/api/controller/weather/WeatherMessageController.kt b/src/main/kotlin/dnd11th/blooming/api/controller/weather/WeatherMessageController.kt
@@ -6,13 +6,11 @@ import dnd11th.blooming.api.service.weather.WeatherService
 import dnd11th.blooming.common.annotation.LoginUser
 import dnd11th.blooming.common.annotation.Secured
 import dnd11th.blooming.domain.entity.user.User
-import io.swagger.v3.oas.annotations.tags.Tag
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RestController
 import java.time.LocalDateTime
 
-@Tag(name = "5. [날씨 메시지]")
 @RestController
 @RequestMapping("/api/v1/weather-message")
 class WeatherMessageController(

diff --git a/src/main/kotlin/dnd11th/blooming/api/dto/region/RegionResponse.kt b/src/main/kotlin/dnd11th/blooming/api/dto/region/RegionResponse.kt
@@ -1,9 +1,16 @@
 package dnd11th.blooming.api.dto.region
 
 import dnd11th.blooming.domain.entity.region.Region
+import io.swagger.v3.oas.annotations.media.Schema
 
+@Schema(
+    name = "Region Response",
+    description = "지역 리스트 결과 응답",
+)
 data class RegionResponse(
+    @field:Schema(name = "id", example = "3")
     val id: Int,
+    @field:Schema(name = "name", example = "서울특별시 송파구 가락2동")
     val name: String,
 ) {
     companion object {

diff --git a/src/main/kotlin/dnd11th/blooming/common/annotation/Secured.kt b/src/main/kotlin/dnd11th/blooming/common/annotation/Secured.kt
@@ -1,8 +1,11 @@
 package dnd11th.blooming.common.annotation
 
+import io.swagger.v3.oas.annotations.security.SecurityRequirement
+
 /**
  * AccessToken이 필요한 API에 적용하는 어노테이션입니다.
  */
+@SecurityRequirement(name = "AccessToken")
 @Retention(AnnotationRetention.RUNTIME)
 @Target(AnnotationTarget.FUNCTION)
 annotation class Secured