각 기능의 API가 많아지다 보니 API 문서화를 위해 스웨거를 사용하기로 하였다

그래서 오늘은 스웨거 문법도 배울 겸 알아보겠다

컨트롤러 스웨거 적용

@Tag(name = "Authentication", description = "인증 관련 API")
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {

	private final AuthService authService;

	@Operation(summary = "회원가입", description = "새로운 사용자를 등록합니다.")
	@PostMapping("/signup")
	public ApiResponse<String> signup(
			@Parameter(description = "회원가입 요청 데이터 (아이디, 비밀번호, 이름)", required = true)
			@Valid @RequestBody SignupDto signupDto) {
		authService.signup(signupDto);
		return ApiResponse.onSuccess("회원가입 성공");
	}

	@Operation(summary = "토큰 재발급", description = "Refresh Token을 사용하여 만료된 Access Token을 재발급합니다. Refresh Token은 쿠키에서, 만료된 Access Token은 헤더에서 가져옵니다.")
	@PostMapping("/reissue")
	public ApiResponse<?> reissue(
			@Parameter(hidden = true) HttpServletRequest request,
			@Parameter(hidden = true) HttpServletResponse response) {

		// Request에서 토큰 추출
		String authorization = request.getHeader("Authorization");
		String accessToken = (authorization != null && authorization.startsWith("Bearer ")) ? authorization.split(" ")[1] : null;
		String refreshToken = CookieUtil.getCookieValue(request, "refresh");

		// 서비스 호출
		TokenDto tokenDto = authService.reissue(accessToken, refreshToken);

		// Response 설정 (헤더 + 쿠키)
		response.setHeader("Authorization", "Bearer " + tokenDto.getAccessToken());
		response.addCookie(CookieUtil.createCookie("refresh", tokenDto.getRefreshToken(), 1209600));

		return ApiResponse.onSuccess("재발급 성공");
	}

	@Operation(summary = "로그인", description = "사용자 이름과 비밀번호로 로그인하여 Access Token 및 Refresh Token을 발급받습니다.")
	@PostMapping("/login")
	public ApiResponse<String> login(
			@Parameter(description = "로그인 요청 데이터 (아이디, 비밀번호)", required = true)
			@Valid @RequestBody LoginDto loginDto,
			@Parameter(hidden = true) HttpServletResponse response) {
		// 서비스 호출
		TokenDto tokenDto = authService.login(loginDto);

		// Response 설정
		response.setHeader("Authorization", "Bearer " + tokenDto.getAccessToken());
		response.addCookie(CookieUtil.createCookie("refresh", tokenDto.getRefreshToken(), 1209600));

		return ApiResponse.onSuccess("로그인 성공");
	}

	@Operation(summary = "로그아웃", description = "Refresh Token을 삭제하고 로그아웃 처리합니다.")
	@PostMapping("/logout")
	public ResponseEntity<String> logout(
			@Parameter(hidden = true) HttpServletRequest request,
			@Parameter(hidden = true) HttpServletResponse response) {
		// 쿠키에서 리프레시 토큰 추출
		String refreshToken = CookieUtil.getCookieValue(request, "refresh");

		// 서비스 호출 (DB 삭제)
		authService.logout(refreshToken);

		// 클라이언트 쿠키 삭제 (항상 수행)
		CookieUtil.deleteCookie(response, "refresh");

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

실제 화면과 비교하면서 보는게 이해하기 쉽다

• @Tag(name = "Authentication", description = "인증 관련 API")
  API가 모여있는 곳의 제목과 설명을 추가한다
  

• @Operation(summary = "회원가입", description = "새로운 사용자를 등록합니다.")
  API의 요약과 설명을 추가한다
  

• @Parameter(description = "회원가입 요청 데이터 (아이디, 비밀번호, 이름)", required = true)
  DTO에 해당 애노테이션을 달면 스웨거 아래 쪽 스키마 모아놓은 곳에 표시된다
  * 표시는 필수 입력해야 한다는 뜻이다
  
  스키마가 아닌 곳에 달면 아래처럼 파라미터 입력하는 칸에 설명이 적힌다
  

간단하게 컨트롤러에만 스웨거를 적용해서 문서화를 해보았다

다른 클래스에도 적용

프로젝트에서는 컨트롤러에만 적용했지만 다른 클래스에도 적용하는 것을 알아보자

DTO 적용

@Data
public class SignupDto {


	@Schema(description = "사용자 이메일", example = "example@naver.com")
	private String username;

	@Schema(description = "비밀번호 (8자 이상)", example = "password123!")
	private String password;

	@Schema(description = "사용자 닉네임", example = "코딩하는산리오")
	private String name;

	public User toEntity(String encodedPassword) {
		return User.builder()
				.username(username)
				.password(encodedPassword)
				.name(name)
				.provider("NONE")
				.role(Role.ROLE_USER)
				.build();
	}
}

회원가입 DTO에 @Schema 를 적용하면 Try it out을 누르면 예시가 미리 적혀있어서 테스트를 빠르게 진행할 수 있다

Config 적용

처음 스웨거를 보면 토큰을 보내는 작업은 어떻게 해야할지 난감하다
SwaggerConfig를 수정해서 보내는 버튼을 만들어주면 된다

@Slf4j
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI(){
        Info info = new Info()
                .title("API")
                .version("1.0")
                .description("API 명세서");

		SecurityScheme securityScheme = new SecurityScheme()
				.type(SecurityScheme.Type.HTTP)
				.scheme("bearer")
				.bearerFormat("JWT")
				.in(SecurityScheme.In.HEADER)
				.name("Authorization");

        return new OpenAPI()
                .components(new Components().addSecuritySchemes("bearerAuth", securityScheme))
                .info(info);
    }

}

SecuritySceme 설정을 해주면 된다
우리는 JWT 방식을 사용하기 때문에 JWT라고 명시하고 헤더는 Authorization이라고 적는다

그러면 Authorize라는 버튼이 생기고 누르면 입력할 수 있는 칸이 나온다
여기에 토큰 값을 넣어서 테스트 하면 된다

스웨거 사용법을 알아보았는데 규모가 큰 프로젝트에는 필수로 사용해야 할 것 같다
자동으로 문서화 해주는게 너무 좋은듯