[SpringBoot] Swagger를 이용한 API 문서 자동화

Swagger

REST API를 문서화하고 테스트할 수 있게 해주는 도구/명세

 

API 개발 시 프론트엔드 개발자나 외부 팀에게 아래 정보를 전달해야 함

• 요청 URL
• HTTP 메서드 (GET, POST 등)
• 요청 파라미터/바디
• 응답 형태

위 내용을 수동 작성하면 코드가 바뀔 때마다 문서도 일일이 따로 수정해야 함

Swagger는 이 과정을 코드에서 자동으로 생성, Controller에 작성된 내용이 Swagger UI에 자동으로 API 표시됨

 

Swagger UI 제공

브라우저에서 시각적으로 API를 확인할 수 있는 인터랙티브 문서 페이지를 제공함

http://localhost:8080/swagger-ui.html

 

• 모든 API 엔드포인트 목록 확인
• 요청/응답 스펙 확인
• 직접 API 호출 테스트 가능 (Postman 필요 X)

 

OpenAPI 명세 생성

API 구조를 표준화된 JSON/YAML 형식으로 내보냄

http://localhost:8080/api-docs

이 파일을 활용해서

• 프론트엔드에서 자동으로 API 클라이언트 코드 생성
• Postman으로 import해서 테스트
• 다른 팀/서비스와 API 스펙 공유 가능

 

 

Springdoc vs Springfox

Spring Boot 프로젝트에서는 springdoc-openapi 라이브러리를 사용하여 Swagger UI 기반으로 API 문서를 자동화 함

예전엔 Springfox Swagger가 많이 사용되었으나, 현재는 springdoc-openapi가 표준처럼 사용됨

 

Springfox Swagger

 

• OpenAPI 2.0 (Swagger 2) 기반
• 2020년 이후 사실상 개발 중단 상태
• Spring Boot 2.6+ 버전과 호환 문제 발생
• Spring Boot 3.x와는 호환 불가
• 설정이 다소 복잡 (별도 Docket Bean 등록 필요)

 

Springdoc

 

• OpenAPI 3.0 기반
• 활발하게 유지보수 중
• Spring Boot 2.x, 3.x 모두 호환
• 설정이 매우 간단 (의존성 추가만 해도 바로 동작)
• Spring Security, WebFlux, Actuator 등과 잘 통합됨

 

 

 

---

Swagger 설정

프로젝트 사양

• Spring Boot 3.3.5
• Gradle
• Java 17

 

의존성 추가

build.gradle에 의존성 추가

이때 SpringBoot 버전마다 호환 가능한 springdoc 버전이 다르므로 아래 공식 문서를 확인할 것. 맞지 않는 버전을 사용할 시 프로젝트가 빌드되지 않고 오류가 날 수 있음

https://springdoc.org/#what-is-the-compatibility-matrix-of-springdoc-openapi-with-spring-boot

dependencies {
    # 현재 프로젝트는 SpringBoot 3.3.5이므로 springdoc 2.6.0 사용
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
}

 

SpringSecurity 사용 시 허용 경로

SpringSecurity 사용 시 SecurityConfig에 Swagger 경로 허용 필요 (사용하지 않으면 필요 X)

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

    http
        .csrf(csrf -> csrf.disable())
        .authorizeHttpRequests(auth -> auth
            .requestMatchers(
                "/swagger-ui/**",
                "/v3/api-docs/**"
            ).permitAll()
            .anyRequest().authenticated()
        );

    return http.build();
}

 

접속

아래 링크로 접속 시 Swagger 접속 가능

이때 application.properties에서 포트 번호나 Context Path를 따로 설정한 경우 적용 필요

http://localhost:8080/swagger-ui/index.html

# 예) Context path로 /api를 설정한 경우
http://localhost:8080/api/swagger-ui/index.html

 

 

Swagger 설정 클래스

API의 기본 정보 설정 가능

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "My API",	// 문서 제목
        version = "v1",		// 버전
        description = "Spring Boot Swagger API 문서"	// 상세설명
    )
)
public class SwaggerConfig {
}

 

Swagger 문서 상세화

Controller 설명

@Tag

@Tag(name = "User API", description = "사용자 관련 API")	// 어노테이션 추가
@RestController
@RequestMapping("/users")
public class UserController {

 

API 설명

@Operation

@Operation(summary = "회원 조회", description = "ID로 회원 정보를 조회합니다.")
@GetMapping("/{id}")
public UserResponse getUser(@PathVariable Long id) {
    return new UserResponse(id, "hayeon");
}

 

 

Response DTO 설명

@Schema

@Getter
@AllArgsConstructor
@Schema(description = "회원 응답 DTO")
public class UserResponse {

    @Schema(description = "회원 ID", example = "1")
    private Long id;

    @Schema(description = "회원 이름", example = "hayeon")
    private String name;
}