[Spring] Swagger(SpringDoc) : API 문서화 + Swagger UI 로그인 테스트

이지연·2026년 2월 3일

백엔드(Java, 알고리즘, spring)

목록 보기

79/89

Swagger란?

Swagger는 Spring Boot 애플리케이션에서 널리 사용되는 API 문서화 도구이고, 개발/테스팅을 지원한다.
REST API의 엔드포인트, 파라미터, 요청/응답 데이터 형식 등을 문서로 정리해주고, UI에서 직접 호출 테스트까지 가능하게 해준다.

Swagger의 주요 목적

1) API 문서화

Swagger를 사용하면 RESTful API의 엔드포인트, 파라미터, 데이터 형식 등을 쉽고 명확하게 문서화할 수 있다.

2) 인터랙티브 UI 제공

Swagger UI는 API 문서를 웹 페이지 형태로 제공하고, 사용자가 직접 API를 호출해볼 수 있는 인터페이스를 제공한다.
즉, Postman 없이도 “문서 + 테스트”를 같이 할 수 있다.

Swagger 사용 방법(SpringDoc 기준)

Spring Boot에서는 보통 springdoc-openapi를 사용한다.

1) 의존성 추가

Gradle 기준으로 아래 의존성을 추가한다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

2) 문서화를 위한 어노테이션 사용

Controller 클래스/메서드에 Swagger(OpenAPI) 어노테이션을 달아서 문서 품질을 올릴 수 있다.

@Operation: 해당 API가 무슨 작업을 하는지 설명하는 용도

예시:

@Operation(
    summary = "회원가입",
    description = "이메일, 비밀번호를 통한 회원가입"
)

(참고) 예전 Swagger2 시절에 보던 value, notes 스타일 설명은 프로젝트에 따라 어노테이션이 다를 수 있는데, SpringDoc(OpenAPI 3) 기준에서는 summary, description을 주로 쓴다.

3) ControllerAdvice는 Swagger 문서에서 제외

전역 예외처리용 @RestControllerAdvice는 API 목록에 노출될 필요가 없으므로 Swagger 문서에서 제외할 수 있다.

@RestControllerAdvice
@Hidden // swagger에서 제외
public class GlobalExceptionHandler {
    // ...
}

로그인 테스트를 위한 Swagger 인증 설정(JWT Bearer)

Swagger UI에서 인증이 필요한 API를 호출하려면, Swagger 쪽에 “인증 스키마”를 등록해야 한다.
아래는 Bearer JWT 인증을 Swagger(OpenAPI)에 등록하는 설정이다.

package com.beyond.order_system.common.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
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 {
    private static final String SECURITY_SCHEME_NAME = "BearerAuth";

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
                .components(
                        new Components().addSecuritySchemes(
                                SECURITY_SCHEME_NAME,
                                new SecurityScheme()
                                        .name(SECURITY_SCHEME_NAME)
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")
                        )
                );
    }
}

이렇게 설정해두면 Swagger UI에서 Authorize 버튼을 통해 토큰을 입력하고, 인증이 필요한 API들을 바로 테스트할 수 있다.

Spring Security 설정: Swagger 경로 예외 처리

운영/개발 환경에서 Swagger 문서 페이지는 인증 없이 접근 가능하게 열어두는 경우가 많다.
그래서 Security 설정에서 아래 경로들을 permitAll()로 예외 처리한다.

.authorizeHttpRequests(a -> a
    .requestMatchers(
        "/member/create",
        "/member/doLogin",
        "/product/list",
        "/member/refresh-at",

        // swagger 사용을 위한 인증 예외처리
        "/v3/api-docs/**",
        "/swagger-ui/**",
        "/swagger-ui.html"
    )
    .permitAll()
    .anyRequest().authenticated()
)
.build();