Spring Security × Swagger로 Bearer JWT 자동 테스트 세팅

 

 

1. 목표 체크

• Swagger UI 상단 “Authorize” 버튼에서 JWT를 한 번만 입력 → 모든 secured 엔드포인트 호출
• 토큰 만료·재발급 시에도 Postman 없이 Swagger 안에서 바로 검증
• 팀원이 새로 합류해도 “로그인 → 버튼 클릭 → 테스트” 3-스텝이면 끝!

---

2. 의존성 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
implementation 'io.jsonwebtoken:jjwt-api:0.12.5'   // JWT 발급·검증
runtimeOnly    'io.jsonwebtoken:jjwt-impl:0.12.5'
runtimeOnly    'io.jsonwebtoken:jjwt-jackson:0.12.5'

이미 spring-security, spring-boot-starter-web 은 포함돼 있다고 가정합니다.

---

3. JWT 발급 컨트롤러 예시

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/auth")
public class AuthController {
  private final JwtProvider jwtProvider;
  private final AuthenticationManager authManager;

  @PostMapping("/login")
  public TokenResponse login(@RequestBody LoginRequest req) {
      Authentication auth = authManager.authenticate(
          new UsernamePasswordAuthenticationToken(req.username(), req.password()));
      String token = jwtProvider.createToken(auth);
      return new TokenResponse(token, "Bearer");
  }
}

• 발급 엔드포인트만 permitAll()로 열어 두고, 나머지는 authenticated()로 묶어 주세요.

---

4. Swagger 전역 Bearer 스키마 설정

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "Article API", version = "v1"),
    security = { @SecurityRequirement(name = "bearerAuth") }
)
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    in = SecuritySchemeIn.HEADER
)
public class SwaggerSecurityConfig {}

• security 속성에 global requirement를 걸었기 때문에, 이후 모든 API가 자동으로 “로그인 필요” 플래그를 달고 나옵니다.
• 특정 공개 API만 열고 싶다면 그 메서드에 @SecurityRequirement(name = "")(빈 값)으로 덮어쓰기.

---

5. Swagger UI에서 자동 테스트하는 3단계

1. /api/v1/auth/login 엔드포인트를 선택하고 “Try it out” → 자격 증명 입력 → Execute
2. 응답으로 내려온 토큰 값을 복사
3. 우측 상단 Authorize 버튼 클릭 후 Bearer ␣<토큰> 붙여넣기 → Authorize

이제 “🔒” 아이콘이 달린 모든 API가 즉시 호출됩니다. 토큰이 만료되면 다시 Step 1-3 반복.

---

6. 개발-운영 프로필별 Swagger 노출 제어

# application-prod.yml
springdoc:
  swagger-ui.enabled: false
  api-docs.enabled: false

운영 서버에서 UI를 잠그면 토큰 유출·스크래핑 위험 최소화!

---

7. 테스트 자동화를 위한 꿀팁 5가지

1. JWT 기본값 주입
   springdoc.swagger-ui.oauth.admin-defined-values=<token> 옵션으로 Authorize 창을 미리 채워 두면 새 토큰 복사-붙여넣기 생략 가능.
2. CI 파이프라인에서 스펙 스냅샷
   Gradle openapi-generator로 HTML 정적 문서를 생성 → S3 혹은 GitHub Pages에 배포해 파트너사도 토큰 없이 열람.
3. MockMvc + JwtDecoder
   통합 테스트에서 @WithMockUser 대신 JwtDecoder를 목킹하면 실제 토큰 없이도 Swagger와 동일한 헤더 구조 검증.
4. Role 기반 필터링
   @PreAuthorize("hasRole('ADMIN')")가 붙은 엔드포인트만 별도 그룹에 묶어 Swagger UI 사이드바를 “Admin” 섹션으로 분리.
5. 토큰 재발급 Flow 표시
   Refresh Token 로직이 있다면 /auth/refresh 엔드포인트에 @Tag(name="Auth")를 달아 한눈에 로그인 흐름 파악.

---

8. 마무리

Swagger-Security 연동으로 “코드 → 문서 → 테스트” 사이클이 완전히 자동화되었습니다.
내일은 OpenAPI Generator로 React·TypeScript SDK를 빌드해, 프런트 엔지니어가 API 스펙을 몰라도 인터페이스 수준에서 완전 타입 안정성을 얻는 방법을 파헤쳐 봅시다!