[Spring Security] 15편 - API 문서를 자동으로! Swagger (SpringDoc) 적용하기

Swagger를 연동하면 현재 작성한 API들이 자동으로 예쁜 문서 사이트로 만들어지고, 심지어 그 사이트에서 버튼 클릭만으로 API 테스트까지 할 수 있습니다.

Spring Boot 3.x 버전에서는 SpringDoc 라이브러리를 사용하는 것이 표준입니다. 빠르게 적용해 봅시다!

---

Step 1. 의존성 추가 (build.gradle)

Spring Boot 3용 springdoc-openapi 라이브러리를 추가합니다.

• 파일: build.gradle

dependencies {
    // ... 기존 의존성 ...

    // Swagger (SpringDoc) - Spring Boot 3.x용
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

(추가 후 우측 상단 코끼리 아이콘(Load Gradle Changes) 클릭 필수!)

---

Step 2. Swagger 설정 클래스 만들기 (SwaggerConfig)

단순히 의존성만 추가해도 동작은 하지만, 우리는 JWT 인증을 쓰고 있기 때문에 설정이 필요합니다.
Swagger 페이지에서도 "토큰을 넣고 요청을 보낼 수 있도록" 설정해줘야 합니다.

• 위치: src/main/java/com/example/board/config/SwaggerConfig.java

package com.example.board.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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("bearer-key",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")))
                .addSecurityItem(new SecurityRequirement().addList("bearer-key"))
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("Spring Boot JWT API Test")
                .description("Spring Security + JWT + Redis + Swagger API 문서")
                .version("1.0.0");
    }
}

[설명]

• SecurityScheme: "이 API 문서는 JWT 토큰(Bearer 방식) 인증을 지원한다"고 명시합니다.
• SecurityRequirement: 모든 API 요청에 이 인증 방식을 적용하겠다고 설정합니다. (이걸 해야 Swagger 화면에 'Authorize' 자물쇠 버튼이 생깁니다.)

---

Step 3. SecurityConfig 경로 허용 (★중요)

이걸 안 하면 Swagger 페이지(index.html)에 접속할 때 403 Forbidden 에러가 뜹니다. 시큐리티가 "누구세요?" 하고 막기 때문입니다.
Swagger 관련 경로들을 인증 없이 접근 가능(permitAll)하게 풀어줘야 합니다.

• 위치: src/main/java/com/example/board/config/SecurityConfig.java

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ... (기존 설정들) ...

            .authorizeHttpRequests((auth) -> auth
                .requestMatchers("/members/login", "/members/join", "/members/reissue").permitAll()

                // ▼ Swagger 관련 경로 허용 (추가) ▼
                .requestMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()

                .requestMatchers("/members/test").hasRole("USER")
                .anyRequest().authenticated()
            )
            // ... (필터 설정들) ...
            ;

        return http.build();
    }

---

Step 4. 컨트롤러에 설명 달기 (선택 사항)

이건 필수는 아니지만, 해두면 문서가 훨씬 예뻐집니다.
@Tag(클래스 설명)와 @Operation(메서드 설명)을 사용합니다.

• 위치: src/main/java/com/example/board/controller/MemberController.java

package com.example.board.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
// ... 기존 import ...

@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/members")
@Tag(name = "Member", description = "회원 관련 API (로그인, 가입, 재발급)") // ★ 컨트롤러 설명
public class MemberController {

    private final MemberService memberService;

    @Operation(summary = "로그인", description = "ID와 PW를 이용하여 Access Token, Refresh Token을 발급합니다.") // ★ 메서드 설명
    @PostMapping("/login")
    public JwtToken login(@RequestBody MemberLoginDto memberLoginDto) {
        // ...
    }

    @Operation(summary = "회원가입", description = "회원가입을 진행합니다.")
    @PostMapping("/join")
    public String join(@RequestBody MemberJoinDto memberJoinDto) {
        // ...
    }

    // ... 나머지도 비슷하게 추가 ...
}

---

Step 5. Swagger 접속 및 테스트

1. 서버를 재실행합니다.
2. 브라우저를 열고 다음 주소로 접속합니다.

• URL: http://localhost:8080/swagger-ui/index.html (또는 /swagger-ui.html)

[사용 방법]

1. 로그인 테스트:

• POST /members/login 탭을 열고 Try it out 클릭.
• JSON Body에 아이디/비번을 넣고 Execute.
• 응답으로 온 accessToken 값을 복사합니다. (따옴표 제외)

1. 인증 설정:

• 화면 우측 상단의 초록색 Authorize 버튼 클릭.
• Value 칸에 복사한 토큰을 붙여넣기 (Bearer 글자 없이 토큰만 넣어도 설정에 따라 동작하지만, 만약 안 되면 Bearer를 앞에 붙여보세요. 위 설정대로면 토큰만 넣어도 됩니다).
• Authorize -> Close 클릭.

1. API 호출:

• 이제 자물쇠가 잠긴 상태(Authenticated)가 되었습니다.
• /members/test 같은 인증이 필요한 API를 Try it out -> Execute 해보세요.
• Postman 없이도 200 OK가 뜨는 것을 확인할 수 있습니다!

---

🎉 마무리

백엔드 코드를 수정하면 문서도 자동으로 업데이트되므로, 나중에 Android 앱을 개발할 때 이 페이지만 띄워놓고 작업하시면 됩니다.
생산성이 2배로 올라가는 마법을 경험해 보세요! 🪄