[멋쟁이사자처럼 부트캠프 TIL 회고] BE 13기_63일차_"Swagger"

🦁멋쟁이사자처럼 백엔드 부트캠프 13기 🦁
TIL 회고 - [63]일차

🚀63일차에는 API 문서화의 Swagger에 대해 배울 수 있었다. 이전에 SpringContextHolder 등의 개념에 대해 다시 복습해보았다.

학습 목표 : Swagger로 만들 수 있는 프로젝트의 명세를 파악할 수 있어야함

학습 과정 : 회고를 통해 작성

---

OAuth2

SpringContextHolder

• Spring의 ApplicationContext를 정적으로 보관하고 접근할 수 있도록 도와주는 유틸리티 클래스
• 빈(Bean) 객체를 전역적으로 조회할 수 있게 해줌
• 일반적으로 @Autowired를 사용하면 빈을 주입받을 수 있지만,
  정적 메서드나 외부 클래스에서 빈을 직접 가져와야 할 때 SpringContextHolder를 활용

@Component
public class SpringContextHolder implements ApplicationContextAware {
    private static ApplicationContext context;

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) {
        context = applicationContext;
    }
    public static <T> T getBean(Class<T> beanClass) {
        return context.getBean(beanClass);
    }
}

// SpringContextHolder사용
MyService myService = SpringContextHolder.getBean(MyService.class);

• ❓SpringContextHolder가 필요한 경우

➡️정적 메서드, 스케줄링 작업, 또는 @Autowired를 사용할 수 없는 외부 라이브러리에서 빈을 조회해야 할 때 필요

---

Authentication 객체

• Spring Security에서 인증된 사용자 정보를 담는 핵심 객체 (=사용자의 로그인 정보 및 권한을 담는 핵심 객체)
• 인증이 성공하면 SecurityContext 내부에 Authentication 객체가 저장
• 이 객체는 현재 로그인한 사용자의 신원, 권한 정보 등을 포함
• SecurityContextHolder를 통해 현재 사용자의 Authentication을 조회 가능
• 주로 UsernamePasswordAuthenticationToken을 사용하여 사용자 인증을 처리

Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
String username = authentication.getName(); // 현재 로그인한 사용자 이름
Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities(); // 권한 목록

• ❓Authentication 객체 생성 시기
  ➡️로그인 인증이 성공하면 Spring Security 필터 체인(SecurityFilterChain)에서 생성됩니다.
  
  
• ❓Authentication 객체 저장 위치
  ➡️SecurityContext 내부에 저장되며, 기본적으로 ThreadLocal을 사용합니다.

---

Authentication의 Principal, Credentials, Authorities

Principal	사용자의 주체 정보 (ex: UserDetails, 사용자 ID)
Credentials	사용자의 인증 수단 (ex: 비밀번호, 토큰)
Authorities	사용자의 권한 목록 (ex: ROLE_USER, ROLE_ADMIN)

• Principal: 현재 로그인한 사용자의 정보
• Credentials: 인증에 사용된 비밀번호 같은 민감한 정보를 포함, 인증 후에는 null로 설정
• Authorities: 사용자의 권한(Role) 목록을 제공, GrantedAuthority 형태로 저장

Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

Object principal = authentication.getPrincipal(); // UserDetails 객체 또는 사용자 ID
Object credentials = authentication.getCredentials(); // 인증 정보 (일반적으로 null)
Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities(); // 권한 목록

• ❓로그인 후 credentials 값
  ➡️ 보안 강화를 위해 credentials는 일반적으로 null 처리
  
  
• ❓Principal이 객체 확인 방법
  ➡️authentication.getPrincipal()을 출력. 보통 UserDetails 또는 사용자 ID

---

SecurityConfig - authorizeHttpRequests()

.authorizeHttpRequests(auth -> auth
        .requestMatchers("/oauth/users/loginform", "/loginform","/userregform", "/").permitAll()
        .requestMatchers("/oauth2/**", "/login/oauth2/code/github", "/registerSocialUser", "/saveSocialUser").permitAll()
        .requestMatchers("/error").permitAll()
        .anyRequest().authenticated()
)

• 동작 흐름 :
  1) OAuth 2.0 인증 과정에서 서버가 리다이렉트 요청을 받음
  2) 사용자가 GitHub 로그인 시도
  3) GitHub은 인증이 완료된 후 redirect_uri에 설정된 URL로 리다이렉트
  3-1) GitHub가 우리 서버로 요청을 보냄
  ➡️GET /login/oauth2/code/github?code=abcdefg123456
  
  4) /login/oauth2/code/github 경로를 허용하지 않으면
  5) Spring Security가 요청을 차단하여 OAuth 2.0 인증이 제대로 동작하지 않음
  
  
• 경로를 허용하게되면
  1) Spring Security는 이 요청을 가로채고,
  2) OAuth2LoginAuthenticationFilter가 code 값을 사용하여 GitHub에 다시 토큰 요청을 보냄
  3) GitHub이 발급한 Access Token을 받아 사용자 정보를 가져옴
  4) 로그인 처리
  5) /login/oauth2/code/github 경로는 반드시 허용(permitAll())해야 OAuth 인증이 정상적으로 완료
  
  
•  /login/oauth2/code/github
  ➡️ GitHub이 인증 후 리다이렉트하는 URL을 허용

---

SecurityConfig - oauth2Login()

.oauth2Login(oauth2 -> oauth2
        .loginPage("/loginform")
        .failureUrl("/loginFailure")
        .userInfoEndpoint(userInfo -> userInfo
                .userService(this.oauth2UserService())
        )
        // 소셜 인증 성공 후 수행할 일
        .successHandler(customOAuth2AuthenticationSuccessHandler)
);

❓userInfoEndpoint() 부분

➡️OAuth 2.0 인증 과정에서 클라이언트가 신뢰할만한 경우에만 사용자 정보를 받을 수 있으며,
userInfoEndpoint()는 해당 정보를 어떻게 다룰지 결정

Spring Security는 기본적으로 DefaultOAuth2UserService를 사용하여 OAuth 2.0 사용자 정보를 가져오며,
이를 상속하거나 감싸서 확장 가능 (=사용자 정보를 DB에 저장하거나, 특정 권한을 부여하는 등의 추가 처리)

💡DefaultOAuth2UserService : OAuth 2.0 제공자(GitHub, Google 등)에서 사용자 정보를 가져오는 기본 서비스

@Bean
public OAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService(){
    DefaultOAuth2UserService delegate = new DefaultOAuth2UserService();
    return oauth2UserRequest -> {
        OAuth2User oAuth2User = delegate.loadUser(oauth2UserRequest);
        
        String token = oauth2UserRequest.getAccessToken().getTokenValue();

        String provider = oauth2UserRequest.getClientRegistration().getRegistrationId();
        String socialId = String.valueOf(oAuth2User.getAttributes().get("id"));
        String username = (String) oAuth2User.getAttributes().get("login");
        String email = (String) oAuth2User.getAttributes().get("email");
        String avatarUrl = (String) oAuth2User.getAttributes().get("avatar_url");

        socialUserService.saveOrUpdateUser(socialId, provider, username, email, avatarUrl);
        return oAuth2User;
    };
}

정리하자면

OAuth 2.0 인증 과정에서 userInfoEndpoint()는 사용자 정보를 가져오는 단계를 담당

1) 인증 요청 : 사용자가 소셜 로그인 버튼 클릭

2) 인가 코드 발급 : 사용자가 OAuth 제공자에서 로그인하면 code를 서버로 전달
➡️사용자가 소셜 로그인을 진행하면 OAuth 서버(GitHub 등)에서 인증을 수행하고 Access Token을 발급

3) Access Token 발급 : code를 사용하여 Access Token 요청 후 사용자 정보 요청
➡️userInfoEndpoint()가 OAuth 서버에 Access Token을 보내서 사용자 정보를 요청

4) 응답을 받은 후 userService(this.oauth2UserService())를 호출하여 사용자 정보 객체(OAuth2User)를 생성

5) 생성된 사용자 정보를 Spring Security가 인증 객체(Authentication)로 변환하여 인증 완료

---

CustomOAuth2AuthenticationSuccessHandler

else{
    SocialLoginInfo socialLoginInfo = socialLoginInfoService.saveSocialLoginInfo(provider, socialId);
    response.sendRedirect("/registerSocialUser?provider="+provider+"&socialId="
            +socialId+"&name="+name+"&uuid="+socialLoginInfo.getUuid());
}

• 회원가입되지 않은 상태일때 추가적으로 가져오고 싶은 데이터가 있으면 /registerSocialUser로 리다이렉트
  ➡️회원가입이 되어 있지 않으면 /registerSocialUser로 리다이렉트하여 추가 정보 입력을 유도하는 것
  
  리다이렉트할때는provider, socialId, name, uuid 등을 추가적으로 얻어내어 보내줌

---

로그아웃 흐름

 

SecurityConfig

.logout(logout -> logout
        .logoutSuccessUrl("/") // 로그아웃이 성공적으로 이루어졌을때 ("/" = /home)으로 갈 것
        .invalidateHttpSession(true)
        .deleteCookies("JSESSIONID") // JSESSIONID의 쿠키를 삭제
);

• .invalidateHttpSession(true)
  ➡️현재 로그인된 세션을 제거하여 세션 기반 로그인 정보를 삭제
  ➡️다시 로그인을 시도하면 새로운 세션이 생성
  
  
• .deleteCookies("JSESSIONID")
  ➡️JSESSIONID 쿠키를 삭제하여 세션 유지가 불가능하도록 처리

---

🚀실습 - Login With Github : 소셜로그인 흐름 확인

• Login With Github 하이퍼링크를 클릭하면 GET 요청으로 이러한 URL이 Github.com에 전달

• 값들을 가져와서 provider, socialId, name, uuid 등을 앱의 서버로 다시 보냄

---

Swagger

• API는 소프트웨어 간 원활한 상호작용을 가능하게 하는 필수적 요소
  (= Swagger : API문서를 자동으로 생성하고 관리할 수 있도록 도와주는 도구)
  
  
• API의 문서화의 필요성에 대해 효과적으로 수행하는 도구가 Swagger
• API의 문서화 : 개발자들이 API를 쉽게 이해하고 사용할 수 있도록
  ➡️API의구조, 요청 및 응답 방식, 인증방법, 오류 코드 등을 정리한 문서 ex. 사용설명서

---

설정 파일 - @config

@Configuration // Configuration을 제외하고 모두 Swagger가 제공하는 어노테이션
@OpenAPIDefinition(
        info = @Info(title = "모임 및 일정 관리 API 문서",
        version = "1.0",
        description = "모임 및 일정을 관리하기 위한 API 문서"
        )
)
public class SwaggerConfig { ... }

• http://localhost:8080/swagger-ui/index.html 접속해보기
  
  
• @OpenAPIDefinition 설정
  @OpenAPIDefinition : OpenAPI의 명세를 설정하는데 사용
  
  info : API문서의 기본정보 (제목, 설명, 버전 등)
  servers : API서버의 URL 설정
  security : 전역 보안 요구 사항 설정 (ex. JWT 인증)

---

AuthController

@RestController
@RequestMapping("/auth")
public class AuthController {
    @Operation(
            summary = "회원가입",
            description = "이메일과 비밀번호를 입력하여 회원가입을 합니다."
    )
    @PostMapping("/register")
    public ResponseEntity<String> register(){
        return ResponseEntity.ok("ok");
    }
}

---

Controller - @Schema로 DTO 연결

RegisterRequestDto

@Getter@Setter
@Schema(description = "회원가입 요청 DTO") // Swagger의 어노테이션
public class RegisterRequestDto {
    // 데이터가 들어가는 부분에 샘플데이터를 지정해서 넣어줄 수 있음
    @Schema(description = "사용자 이메일", example = "user@example.com")
    private String email;

    @Schema(description = "사용자 비밀번호", example = "password123")
    private String password;
}

---

AuthController의 register()메소드

@PostMapping("/register")
public ResponseEntity<String> register(@RequestBody RegisterRequestDto requestDto){
    // ...
    return ResponseEntity.ok("ok");
}

• 인자로 RegisterRequestDto 추가

• 장점 : Try it out으로 데이터들을 테스트 가능

---

SwaggerConfig 설정 추가

@Configuration
@OpenAPIDefinition(
        info = @Info(title = "모임 및 일정 관리 API",
                version = "1.0",
                description = "모임 및 일정을 관리하기 위한 API 문서"
        )
        ,security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
        name = "bearerAuth",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT"
)
public class SwaggerConfig {
}

• Scheme 관련하여 bearer 추가

---

Controller - 로그아웃, 사용자 목록/정보 조회 메소드 추가

@PostMapping("/logout")
public ResponseEntity<String> logout(
        @Parameter(description = "JWT 인증 토큰", required = true, example = "Bearer eyJhbGciOiJIUzI....")
        @RequestHeader("Authorization") String token
){

    return ResponseEntity.ok("로그아웃 성공");
}

@Operation(summary = "사용자 목록 조회", description = "사용자 목록을 페이지 단위로 조회합니다.")
@GetMapping("/users")
public ResponseEntity<List<UserDto>> getUsers(
        @RequestParam(value = "page", required = false, defaultValue = "1") int page,
        @RequestParam(value = "size", required = false, defaultValue = "10") int size) {
//        List<UserDto> users = userService.getUsers(page, size);
    return ResponseEntity.ok(null);
}
@Operation(summary = "사용자 정보 조회", description = "사용자의 고유 ID를 이용하여 정보를 조회합니다.")
@GetMapping("/users/{id}")
public ResponseEntity<UserDto> getUserById(
        @PathVariable("id") Long id) {
//        UserDto user = userService.getUserById(id);
    return ResponseEntity.ok(null);
}

• @Operation, @Parameter 등으로 API 문서에 넣을 콘텐츠를 설정할 수 있다.

---

🚀회고 결과 :

Swagger의 핵심 개념에 대해서 알 수 있었다. 이를 통해 프로젝트를 어떻게 구성해야할지를 좀 더 학습할 수 있었다.

향후 계획 : 

- Swagger를 활용한 모임 프로젝트 명세서 분석