[FEAT] Docs 작업(Swagger, Security, Cors) (#77)

Be-HinD · web-flow · commit 22fff8d0c472 · 2025-12-11T16:13:09.000+09:00
* 📝docs: Swagger 작업 진행

* ✨feat: 인증/인가 추가 작업

* ✨feat: cors 작업

* 🐛fix: 코드 리뷰 피드백 반영
diff --git a/build.gradle b/build.gradle
@@ -45,6 +45,8 @@ dependencies {
     developmentOnly 'com.h2database:h2'
     testImplementation 'com.h2database:h2'
 
+    //Swagger
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'
 
 }
 
diff --git a/src/main/java/team/wego/wegobackend/auth/application/AuthService.java b/src/main/java/team/wego/wegobackend/auth/application/AuthService.java
@@ -71,10 +71,10 @@ public LoginResponse login(LoginRequest request) {
             throw new DeletedUserException();
         }
 
-        String accessToken = jwtTokenProvider.createAccessToken(user.getEmail(),
+        String accessToken = jwtTokenProvider.createAccessToken(user.getId(), user.getEmail(),
             user.getRole().name());
 
-        String refreshToken = jwtTokenProvider.createRefreshToken(user.getEmail());
+        String refreshToken = jwtTokenProvider.createRefreshToken(user.getId(), user.getEmail());
 
         Long expiresIn = jwtTokenProvider.getAccessTokenExpiresIn();
 
@@ -99,10 +99,8 @@ public RefreshResponse refresh(String refreshToken) {
             throw new DeletedUserException();
         }
 
-        String newAccessToken = jwtTokenProvider.createAccessToken(
-            user.getEmail(),
-            user.getRole().name()
-        );
+        String newAccessToken = jwtTokenProvider.createAccessToken(user.getId(), user.getEmail(),
+            user.getRole().name());
 
         Long expiresIn = jwtTokenProvider.getAccessTokenExpiresIn();
 
diff --git a/src/main/java/team/wego/wegobackend/auth/presentation/AuthController.java b/src/main/java/team/wego/wegobackend/auth/presentation/AuthController.java
@@ -25,7 +25,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/auth")
-public class AuthController {
+public class AuthController implements AuthControllerDocs {
 
     private final AuthService authService;
 
diff --git a/src/main/java/team/wego/wegobackend/auth/presentation/AuthControllerDocs.java b/src/main/java/team/wego/wegobackend/auth/presentation/AuthControllerDocs.java
@@ -0,0 +1,36 @@
+package team.wego.wegobackend.auth.presentation;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.CookieValue;
+import org.springframework.web.bind.annotation.RequestBody;
+import team.wego.wegobackend.auth.application.dto.request.LoginRequest;
+import team.wego.wegobackend.auth.application.dto.request.SignupRequest;
+import team.wego.wegobackend.auth.application.dto.response.LoginResponse;
+import team.wego.wegobackend.auth.application.dto.response.RefreshResponse;
+import team.wego.wegobackend.auth.application.dto.response.SignupResponse;
+import team.wego.wegobackend.common.response.ApiResponse;
+
+@Tag(name = "인증/인가 API", description = "인증 및 인가에 대한 API 리스트 \uD83D\uDC08")
+public interface AuthControllerDocs {
+
+    @Operation(summary = "회원가입", description = "회원가입을 위한 엔드포인트")
+    ResponseEntity<ApiResponse<SignupResponse>> signup(
+        @Valid @RequestBody SignupRequest request);
+
+    @Operation(summary = "로그인", description = "로그인을 위한 엔드포인트")
+    ResponseEntity<ApiResponse<LoginResponse>> login(
+        @Valid @RequestBody LoginRequest request,
+        HttpServletResponse response);
+
+    @Operation(summary = "로그아웃", description = "리프레시 토큰 쿠키만 삭제합니다.")
+    ResponseEntity<ApiResponse<Void>> logout(HttpServletResponse response);
+
+    @Operation(summary = "액세스 토큰 재발급", description = "리프레시 토큰 만료가 안되었을 경우 액세스 토큰을 재발급합니다.")
+    ResponseEntity<ApiResponse<RefreshResponse>> refresh(
+        @CookieValue(name = "refreshToken", required = false) String refreshToken);
+    
+}
diff --git a/src/main/java/team/wego/wegobackend/common/config/CorsConfig.java b/src/main/java/team/wego/wegobackend/common/config/CorsConfig.java
@@ -0,0 +1,27 @@
+package team.wego.wegobackend.common.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.CorsRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class CorsConfig {
+    @Bean
+    public WebMvcConfigurer corsConfigurer() {
+        return new WebMvcConfigurer() {
+            @Override
+            public void addCorsMappings(CorsRegistry registry) {
+                registry.addMapping("/**")
+                    .allowedOrigins(
+                        "http://localhost:3000",
+                        "https://wego.monster"
+                    )
+                    .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
+                    .allowedHeaders("*")
+                    .allowCredentials(true)
+                    .maxAge(3600);
+            }
+        };
+    }
+}
diff --git a/src/main/java/team/wego/wegobackend/common/config/SwaggerConfig.java b/src/main/java/team/wego/wegobackend/common/config/SwaggerConfig.java
@@ -0,0 +1,40 @@
+package team.wego.wegobackend.common.config;
+
+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.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import java.util.List;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SwaggerConfig {
+
+    @Bean
+    public OpenAPI openAPI() {
+        SecurityScheme securityScheme = new SecurityScheme()
+            .type(SecurityScheme.Type.HTTP)
+            .scheme("bearer")
+            .bearerFormat("JWT")
+            .in(SecurityScheme.In.HEADER)
+            .name("Authorization");
+
+        SecurityRequirement securityRequirement = new SecurityRequirement()
+            .addList("bearerAuth");
+
+        return new OpenAPI()
+            .components(new Components()
+                .addSecuritySchemes("bearerAuth", securityScheme))
+            .security(List.of(securityRequirement))
+            .info(apiInfo());
+    }
+
+    private Info apiInfo() {
+        return new Info()
+            .title("WeGo-API Documentation")
+            .description("Welcome To WeGo-API Documentation \uD83D\uDE0A")
+            .version("1.0.0");
+    }
+}
diff --git a/src/main/java/team/wego/wegobackend/common/security/JwtAuthenticationFilter.java b/src/main/java/team/wego/wegobackend/common/security/JwtAuthenticationFilter.java
@@ -2,7 +2,6 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.servlet.FilterChain;
-import jakarta.servlet.ServletException;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import java.io.IOException;
@@ -12,11 +11,11 @@
 import org.springframework.http.HttpStatus;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.context.SecurityContextHolder;
-import org.springframework.security.core.userdetails.UserDetails;
 import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
 import org.springframework.stereotype.Component;
 import org.springframework.util.AntPathMatcher;
 import org.springframework.util.StringUtils;
+import org.springframework.web.cors.CorsUtils;
 import org.springframework.web.filter.OncePerRequestFilter;
 import team.wego.wegobackend.auth.exception.UserNotFoundException;
 import team.wego.wegobackend.common.response.ErrorResponse;
@@ -53,7 +52,7 @@ protected void doFilterInternal(HttpServletRequest request, HttpServletResponse
 
                 String email = jwtTokenProvider.getEmailFromToken(jwt);
 
-                UserDetails userDetails = userDetailsService.loadUserByUsername(email);
+                CustomUserDetails userDetails = (CustomUserDetails) userDetailsService.loadUserByUsername(email);
 
                 UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                     userDetails, null, userDetails.getAuthorities());
@@ -66,11 +65,16 @@ protected void doFilterInternal(HttpServletRequest request, HttpServletResponse
 
                 log.debug("JWT 인증 성공: {}", email);
 
-                filterChain.doFilter(request, response);
-                return;
             }
+            else {
+                if(!isPublicEndpoint(request)) {
+                    sendJsonError(response, "토큰을 찾을 수 없습니다.");
+                    return;
+                }
+            }
+
+            filterChain.doFilter(request, response);
 
-            sendJsonError(response, "토큰을 찾을 수 없습니다.");
 
         } catch (ExpiredTokenException | InvalidTokenException |UserNotFoundException e) {
             sendJsonError(response, e.getMessage());
@@ -107,4 +111,25 @@ private void sendJsonError(HttpServletResponse response, String message) throws
 
         objectMapper.writeValue(response.getWriter(), errorResponse);
     }
+
+    /**
+     * Public 엔드포인트 확인
+     */
+    private boolean isPublicEndpoint(HttpServletRequest request) {
+        String path = request.getRequestURI();
+        String method = request.getMethod();
+
+        if (CorsUtils.isPreFlightRequest(request)) {
+            return true;
+        }
+
+        //TODO : PUBLIC_PATTERNS 관리 포인트 개선 필요 (메서드까지 관리 확장)
+        if ("GET".equals(method) && pathMatcher.match("/api/v1/users/*", path)) {
+            return true;
+        }
+
+        // SecurityEndpoints.PUBLIC_PATTERNS 체크
+        return Arrays.stream(SecurityEndpoints.PUBLIC_PATTERNS)
+            .anyMatch(pattern -> pathMatcher.match(pattern, path));
+    }
 }
diff --git a/src/main/java/team/wego/wegobackend/common/security/SecurityConfig.java b/src/main/java/team/wego/wegobackend/common/security/SecurityConfig.java
@@ -3,6 +3,7 @@
 import lombok.RequiredArgsConstructor;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.http.HttpMethod;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
 import org.springframework.security.config.annotation.web.configurers.HeadersConfigurer.FrameOptionsConfig;
@@ -29,6 +30,7 @@ public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 
         http
             .authorizeHttpRequests((auth) -> auth
+                .requestMatchers(HttpMethod.GET, "/api/v1/users/*").permitAll()
                 .requestMatchers(SecurityEndpoints.PUBLIC_PATTERNS).permitAll()
                 .anyRequest().authenticated()
             );
diff --git a/src/main/java/team/wego/wegobackend/common/security/SecurityEndpoints.java b/src/main/java/team/wego/wegobackend/common/security/SecurityEndpoints.java
@@ -4,9 +4,15 @@ public class SecurityEndpoints {
 
     public static final String[] PUBLIC_PATTERNS = {
         "/api/v*/auth/**",
-        "/api/v*/docs/**",
         "/api/v*/health",
         "/h2-console/**",
-        "/error"
+        "/error",
+
+        //SpringDoc
+        "/swagger-ui/**",
+        "/swagger-ui.html",
+        "/api-docs/**",
+        "/v*/api-docs/**",
     };
+
 }
diff --git a/src/main/java/team/wego/wegobackend/common/security/jwt/JwtTokenProvider.java b/src/main/java/team/wego/wegobackend/common/security/jwt/JwtTokenProvider.java
@@ -46,20 +46,21 @@ protected void init() {
     /**
      * JWT 토큰 생성
      */
-    public String createAccessToken(String email, String role) {
-        return createToken(email, role, accessTokenExpiration, "access");
+    public String createAccessToken(Long userId, String email, String role) {
+        return createToken(userId, email, role, accessTokenExpiration, "access");
     }
 
-    public String createRefreshToken(String email) {
-        return createToken(email, null, refreshTokenExpiration, "refresh");
+    public String createRefreshToken(Long userId, String email) {
+        return createToken(userId, email, null, refreshTokenExpiration, "refresh");
     }
 
-    private String createToken(String email, String role, long expiration, String type) {
+    private String createToken(Long userId, String email, String role, long expiration, String type) {
         Date now = new Date();
         Date expiryDate = new Date(now.getTime() + expiration);
 
         JwtBuilder builder = Jwts.builder()
             .subject(email)
+            .claim("userId", userId)
             .claim("type", type)
             .issuedAt(now)
             .expiration(expiryDate);
@@ -71,12 +72,16 @@ private String createToken(String email, String role, long expiration, String ty
         return builder.signWith(secretKey, Jwts.SIG.HS256).compact();
     }
 
+    public String getTokenUserId(String token) {
+        return getClaims(token).get("userId", String.class);
+    }
+
     public String getEmailFromToken(String token) {
         return getClaims(token).getSubject();
     }
 
-    public String getRoleFromToken(String token) {
-        return getClaims(token).get("role", String.class);
+    public Long getRoleFromToken(String token) {
+        return getClaims(token).get("role", Long.class);
     }
 
     public String getTokenType(String token) {
diff --git a/src/main/java/team/wego/wegobackend/user/presentation/UserController.java b/src/main/java/team/wego/wegobackend/user/presentation/UserController.java
@@ -27,7 +27,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/v1/users")
-public class UserController {
+public class UserController implements UserControllerDocs{
 
     private final UserService userService;
 
@@ -47,6 +47,7 @@ public ResponseEntity<ApiResponse<String>> test(
 
     @GetMapping("/{userId}")
     public ResponseEntity<ApiResponse<UserInfoResponse>> profile(@PathVariable Long userId) {
+        log.debug("프로필 조회 API 호출");
         UserInfoResponse response = userService.getProfile(userId);
 
         return ResponseEntity
diff --git a/src/main/java/team/wego/wegobackend/user/presentation/UserControllerDocs.java b/src/main/java/team/wego/wegobackend/user/presentation/UserControllerDocs.java
@@ -0,0 +1,45 @@
+package team.wego.wegobackend.user.presentation;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RequestPart;
+import org.springframework.web.multipart.MultipartFile;
+import team.wego.wegobackend.common.response.ApiResponse;
+import team.wego.wegobackend.common.security.CustomUserDetails;
+import team.wego.wegobackend.user.application.dto.request.ProfileUpdateRequest;
+import team.wego.wegobackend.user.application.dto.response.UserInfoResponse;
+
+@Tag(name = "유저 API", description = "유저와 관련된 API 리스트 \uD83D\uDC08")
+public interface UserControllerDocs {
+
+    @Operation(summary = "테스트 API", description = "서버 로직 테스트를 위한 엔드포인트입니다.")
+    ResponseEntity<ApiResponse<String>> test(
+        @AuthenticationPrincipal CustomUserDetails userDetails);
+
+    @Operation(summary = "유저 프로필 조회 API", description = "PathVariable로 들어온 userId에 해당하는 유저 프로필에 대한 응답")
+    ResponseEntity<ApiResponse<UserInfoResponse>> profile(@PathVariable Long userId);
+
+    @Operation(summary = "프로필 이미지 변경 API", description = "토큰 주인장 이미지만 변경 가능합니다.")
+    ResponseEntity<ApiResponse<UserInfoResponse>> profileImage(
+        @AuthenticationPrincipal CustomUserDetails userDetails,
+        @RequestPart("file") MultipartFile file
+    );
+
+    @Operation(summary = "유저 프로필 변경 API", description = "토큰 주인장 프로필만 변경 가능합니다.")
+    ResponseEntity<ApiResponse<UserInfoResponse>> profileInfo(
+        @AuthenticationPrincipal CustomUserDetails userDetails,
+        @Valid @RequestBody ProfileUpdateRequest request
+    );
+
+    @Operation(summary = "알림 설정 변경 API", description = "알림 ON/OFF 플래그 설정")
+    ResponseEntity<ApiResponse<UserInfoResponse>> changeNotificationConfig(
+        @AuthenticationPrincipal CustomUserDetails userDetails,
+        @RequestParam(required = true) Boolean isNotificationEnabled
+    );
+}

Original file line number	Diff line number	Diff line change
`@@ -45,6 +45,8 @@ dependencies {`
`45`	`45`	`developmentOnly 'com.h2database:h2'`
`46`	`46`	`testImplementation 'com.h2database:h2'`
`47`	`47`
	`48`	`+ //Swagger`
	`49`	`+ implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'`
`48`	`50`
`49`	`51`	`}`
`50`	`52`