[#73]; chore: swagger oauth2 추가

leeminseo0923 · leeminseo0923 · commit 26fce2f77e23 · 2025-09-12T15:59:18.000+09:00
diff --git a/src/main/kotlin/com/yourssu/scouter/common/application/domain/authentication/AuthenticationController.kt b/src/main/kotlin/com/yourssu/scouter/common/application/domain/authentication/AuthenticationController.kt
@@ -9,6 +9,7 @@ import com.yourssu.scouter.common.implement.domain.authentication.TokenType
 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.security.SecurityRequirements
 import io.swagger.v3.oas.annotations.tags.Tag
 import jakarta.servlet.http.HttpServletRequest
 import jakarta.validation.Valid
@@ -34,6 +35,7 @@ class AuthenticationController(
 
     @Tag(name = "OAUTH2")
     @Operation(summary = "회원가입/로그인", description = "/oauth2/{oauth2Type}에서 얻은 code를 이용해 회원가입/로그인을 진행합니다.")
+    @SecurityRequirements // 로그인을 필요로 하지 않는 곳은 전역 인증을 사용하지않도록 초기화
     @PostMapping("oauth2/login/{oauth2Type}")
     fun login(
         @PathVariable oauth2Type: OAuth2Type,
@@ -60,6 +62,7 @@ class AuthenticationController(
     @ApiResponse(description = "NO_CONTENT", responseCode = "204")
     @PostMapping("/logout")
     fun logout(
+        @Parameter(hidden = true)
         @RequestHeader(HttpHeaders.AUTHORIZATION) accessToken: String,
         @RequestBody @Valid request: LogoutRequest,
     ): ResponseEntity<Unit> {
@@ -68,9 +71,11 @@ class AuthenticationController(
         return ResponseEntity.noContent().build()
     }
 
+    @SecurityRequirements // 로그인을 필요로 하지 않는 곳은 전역 인증을 사용하지않도록 초기화
     @Operation(summary = "AccessToken 유효성 검사")
     @GetMapping("/validate-token")
     fun validateToken(
+        @Parameter(hidden = true)
         @RequestHeader(HttpHeaders.AUTHORIZATION) accessToken: String,
     ): ResponseEntity<ValidateTokenResponse> {
         val validated: Boolean = authenticationService.isValidToken(TokenType.ACCESS, accessToken)
@@ -79,10 +84,12 @@ class AuthenticationController(
         return ResponseEntity.ok(response)
     }
 
+    @SecurityRequirements // 로그인을 필요로 하지 않는 곳은 전역 인증을 사용하지않도록 초기화
     @Operation(summary = "토큰 재발급")
     @PostMapping("/refresh-token")
     fun refreshToken(
         @RequestBody @Valid request: TokenRefreshRequest,
+        @Parameter(hidden = true)
         @RequestHeader(HttpHeaders.AUTHORIZATION, required = false) bearerRefreshHeader: String?,
     ): ResponseEntity<TokenRefreshResponse> {
         logger.info("[Auth] POST /refresh-token | hasAuthHeader={} | bodyPresent={}", !bearerRefreshHeader.isNullOrBlank(), !request.refreshToken.isNullOrBlank())
@@ -98,6 +105,7 @@ class AuthenticationController(
     @ApiResponse(description = "NO_CONTENT", responseCode = "204")
     @PostMapping("/withdrawal")
     fun withdraw(
+        @Parameter(hidden = true)
         @RequestHeader(HttpHeaders.AUTHORIZATION) accessToken: String,
         @RequestBody @Valid request: WithdrawalRequest,
     ): ResponseEntity<Unit> {
diff --git a/src/main/kotlin/com/yourssu/scouter/common/application/domain/authentication/OAuth2Controller.kt b/src/main/kotlin/com/yourssu/scouter/common/application/domain/authentication/OAuth2Controller.kt
@@ -2,6 +2,9 @@ package com.yourssu.scouter.common.application.domain.authentication
 
 import com.yourssu.scouter.common.business.domain.authentication.OAuth2Service
 import com.yourssu.scouter.common.implement.domain.authentication.OAuth2Type
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.security.SecurityRequirements
+import io.swagger.v3.oas.annotations.tags.Tag
 import jakarta.servlet.http.HttpServletRequest
 import jakarta.servlet.http.HttpServletResponse
 import org.springframework.http.HttpHeaders
@@ -12,11 +15,15 @@ import org.springframework.web.bind.annotation.RequestParam
 import org.springframework.web.bind.annotation.RestController
 import org.springframework.web.util.UriComponentsBuilder
 
+@Tag(name = "인증/인가")
+@Tag(name = "OAUTH2")
 @RestController
 class OAuth2Controller(
     private val oauth2Service: OAuth2Service
 ) {
 
+    @Operation(summary = "OAuth2 로그인 페이지 리다이렉트", description = "여기에서는 리다이렉트가 되지 않습니다. Authorize 이용.")
+    @SecurityRequirements // 로그인을 필요로 하지 않는 곳은 전역 인증을 사용하지않도록 초기화
     @GetMapping("/oauth2/{oauth2Type}")
     fun redirectAuthCodeRequestUrl(
         @PathVariable oauth2Type: OAuth2Type,
diff --git a/src/main/kotlin/com/yourssu/scouter/common/application/domain/authentication/SwaggerOAuth2Controller.kt b/src/main/kotlin/com/yourssu/scouter/common/application/domain/authentication/SwaggerOAuth2Controller.kt
@@ -0,0 +1,46 @@
+package com.yourssu.scouter.common.application.domain.authentication
+
+import com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy
+import com.fasterxml.jackson.databind.annotation.JsonNaming
+import com.yourssu.scouter.common.business.domain.authentication.LoginResult
+import com.yourssu.scouter.common.business.domain.authentication.OAuth2Service
+import com.yourssu.scouter.common.implement.domain.authentication.OAuth2Type
+import io.swagger.v3.oas.annotations.Hidden
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.http.ResponseEntity
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.springframework.web.bind.annotation.RestController
+
+@Hidden
+@RestController
+class SwaggerOAuth2Controller(private val oauth2Service: OAuth2Service) {
+
+    @Value("\${springdoc.swagger-ui.oauth2-redirect-url}")
+    private lateinit var redirectUri: String
+
+    @PostMapping("/oauth2/swagger/callback")
+    fun callback(
+        @RequestParam code: String,
+        @RequestParam(required = false) error: String?
+    ): ResponseEntity<AuthResponse> {
+        if (error != null) throw RuntimeException(
+            "OAuth2 authorization code flow failed: $error"
+        )
+
+        val referer = redirectUri.substringBefore("/")
+        val loginResult: LoginResult = oauth2Service.login(
+            oauth2Type = OAuth2Type.GOOGLE, // 인증, 인가 로직을 시험하기 위함이 아니기 때문에 google로 고정해뒀습니다.
+            oauth2AuthorizationCode = code,
+            referer = referer,
+            redirectUriOverride = redirectUri,
+        )
+        val accessToken = loginResult.accessToken.substringAfter(" ")
+        return ResponseEntity.ok(AuthResponse(accessToken))
+    }
+}
+
+@JsonNaming(SnakeCaseStrategy::class)
+data class AuthResponse(val accessToken: String)
+
+
diff --git a/src/main/kotlin/com/yourssu/scouter/common/application/support/configuration/SwaggerConfiguration.kt b/src/main/kotlin/com/yourssu/scouter/common/application/support/configuration/SwaggerConfiguration.kt
@@ -3,6 +3,9 @@ package com.yourssu.scouter.common.application.support.configuration
 import io.swagger.v3.oas.models.Components
 import io.swagger.v3.oas.models.OpenAPI
 import io.swagger.v3.oas.models.info.Info
+import io.swagger.v3.oas.models.security.OAuthFlow
+import io.swagger.v3.oas.models.security.OAuthFlows
+import io.swagger.v3.oas.models.security.Scopes
 import io.swagger.v3.oas.models.security.SecurityRequirement
 import io.swagger.v3.oas.models.security.SecurityScheme
 import org.springframework.context.annotation.Bean
@@ -12,27 +15,46 @@ import org.springframework.context.annotation.Configuration
 class SwaggerConfiguration {
 
     companion object {
-        const val JWT = "JWT"
-        const val BEARER = "Bearer"
+        const val OAUTH2 = "oauth2"
     }
 
     @Bean
     fun customOpenAPI() : OpenAPI {
-        val securityRequirement = SecurityRequirement().addList(JWT)
-        val components = Components().addSecuritySchemes(
-            JWT, SecurityScheme()
-                .name(JWT)
-                .type(SecurityScheme.Type.HTTP)
-                .scheme(BEARER)
-                .bearerFormat(JWT)
-        )
+        val securityRequirement = SecurityRequirement().addList(OAUTH2)
+        val components = Components()
+            .addSecuritySchemes(OAUTH2, createGoogleOAuth2Scheme())
         return OpenAPI()
             .components(Components())
             .info(info())
             .addSecurityItem(securityRequirement)
             .components(components)
     }
 
+    private fun createGoogleOAuth2Scheme() : SecurityScheme {
+        return SecurityScheme()
+            .type(SecurityScheme.Type.OAUTH2)
+            .flows(
+                OAuthFlows()
+                    .authorizationCode(
+                        OAuthFlow()
+                            .authorizationUrl("https://accounts.google.com/o/oauth2/auth")
+                            .tokenUrl("http://localhost:8080/oauth2/swagger/callback")
+                            .refreshUrl("http://localhost:8080/oauth2/swagger/callback")
+                            .scopes(createGoogleScopes())
+                    )
+            )
+    }
+
+    private fun createGoogleScopes() : Scopes {
+        return Scopes()
+            .addString("openid", "OpenId Connect")
+            .addString("profile", "기본 프로필 정보")
+            .addString("email", "이메일 주소")
+            .addString("https://www.googleapis.com/auth/drive.readonly", "드라이브 읽기 권한")
+            .addString("https://www.googleapis.com/auth/forms.responses.readonly", "구글 폼 응답 읽기 권한")
+            .addString("https://www.googleapis.com/auth/gmail.send", "메일 전송 권한")
+    }
+
     private fun info() : Info {
         return Info()
             .title("Scouter API")
diff --git a/src/main/resources/application-local.yml b/src/main/resources/application-local.yml
@@ -38,6 +38,7 @@ oauth2:
     allowed_redirect_uris:
       - ${ALLOWED_REDIRECT_URI_LOCAL}
       - ${ALLOWED_REDIRECT_URI_DEV}
+      - ${SWAGGER_OAUTH2_REDIRECT_URL}
     scope:
       - openid
       - https://www.googleapis.com/auth/userinfo.email
@@ -52,4 +53,8 @@ springdoc:
       theme: arta # syntax highlight theme
     doc-expansion: none # 기본으로 접기
     operations-sorter: method # 정렬 방식
-    tags-sorter: alpha
+    tags-sorter: alpha
+    oauth:
+      client-id: ${GOOGLE_OAUTH_CLIENT_ID}
+      client-secret: ${GOOGLE_OAUTH_CLIENT_SECRET}
+    oauth2-redirect-url: ${SWAGGER_OAUTH2_REDIRECT_URL}
