[Java Spring Boot] 스프링 부트에서 Swagger 사용하기

📢 [Java Spring Boot] 스프링 부트에서 Swagger 사용하기

🙌 Swagger는 API 문서를 자동으로 생성해주는 도구로, Spring Boot에서는 Springdoc OpenAPI 라이브러리를 사용하여 쉽게 설정할 수 있습니다.

📝 Swagger(OpenAPI)란?

🙌 Swagger는 REST API를 시각화하여 쉽게 테스트하고 문서를 자동으로 생성해주는 도구입니다.
Spring Boot에서는 주로 springdoc-openapi 라이브러리를 사용하여 Swagger UI를 제공하며, 이를 통해 API를 웹 브라우저에서 손쉽게 확인할 수 있습니다.

📝 Spring Boot에서 Swagger 적용하기

    ✅ springdoc-openapi 의존성 추가

    ✔ Spring Boot 2.x 이상에서는 springdoc-openapi 라이브러리를 사용합니다.
    ✔ Spring Boot 프로젝트에서 다음과 같은 의존성을 추가합니다.

// Gradle - build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5'

// Maven - pom.xml
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.5</version> 
</dependency>

    ✅ Swagger UI 확인하기

      🙌 의존성을 추가한 후 프로젝트를 실행하면, Swagger UI를 확인할 수 있습니다.

      ✔ 기본적으로 http://localhost:8080/swagger-ui.html 주소에서 Swagger UI가 제공됩니다.
      ✔ OpenAPI JSON 문서는 http://localhost:8080/v3/api-docs에서 확인할 수 있습니다.


👉 실행 결과 

📝 Swagger 문서화 추가하기

🙌 Swagger에서 API를 보기 좋게 표시하려면, @Operation 및 @Parameter 등의 어노테이션을 활용합니다.

    ✅ Controller에서 API 문서 작성하기

      ✔  @Tag(name, description): API 그룹을 지정합니다.
      ✔  @Operation(summary, description): API의 제목과 설명을 추가합니다.
      ✔  @Parameter(description): 요청 파라미터에 대한 설명을 추가합니다.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.ArrayList;

@RestController
@RequestMapping("/users")
@Tag(name = "User API", description = "사용자 관리 API")  // API 그룹 태그
public class UserController {

    private final List<String> users = new ArrayList<>();

    @GetMapping
    @Operation(summary = "모든 사용자 조회", description = "저장된 모든 사용자 목록을 조회합니다.")
    public List<String> getUsers() {
        return users;
    }

    @PostMapping
    @Operation(summary = "사용자 추가", description = "새로운 사용자를 추가합니다.")
    public String addUser(@RequestParam @Parameter(description = "추가할 사용자 이름") String name) {
        users.add(name);
        return "User added: " + name;
    }
}

    ✅ DTO(데이터 전송 객체) 문서화

      ✔ Swagger에서 DTO를 자동으로 문서화하려면, @Schema 어노테이션을 사용합니다.

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@Schema(description = "사용자 정보 DTO")
public class UserDto {

    @Schema(description = "사용자 ID", example = "1")
    private Long id;

    @Schema(description = "사용자 이름", example = "홍길동")
    private String name;
}

👉 실행 결과 

 

📝 Swagger 설정 변경하기

🙌 Swagger의 기본 설정을 변경하려면 application.yml 또는 application.properties에서 설정을 추가합니다.

    ✅ API 기본 정보 설정

// application.yml
springdoc:
  api-docs:
    path: /api-docs  # API 문서 경로 변경
  swagger-ui:
    path: /swagger-ui  # Swagger UI 경로 변경
    operationsSorter: method  # API 정렬 방식 (method 기준)
    disable-swagger-default-url: true  # 기본 Swagger URL 비활성화


// application.properties
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.disable-swagger-default-url=true

 

📝 보안 설정 (Swagger UI 접근 제한)

🙌  Swagger는 개발 및 테스트 환경에서 유용하지만, 운영 환경에서는 보안이 필요합니다.
🙌  Spring Security를 사용하는 경우 Swagger에 대한 접근을 제한할 수 있습니다.

    ✅ Spring Security 설정 추가

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .anyRequest().authenticated()
            )
            .csrf(csrf -> csrf.disable());  // CSRF 비활성화 (개발 환경)

        return http.build();
    }
}

 

📝 Swagger UI에서 API 테스트하기

🙌 이제 Swagger UI에서 API를 테스트할 수 있습니다.

    ✅ Swagger UI 접속

      ✔ 브라우저에서 http://localhost:8080/swagger-ui.html 열기

    ✅ API 테스트

      ✔  GET /users 실행 → 모든 사용자 목록 확인
      ✔  POST /users?name=홍길동 실행 → 사용자 추가
      ✔  다시 GET /users 실행 → 추가된 사용자 확인

---

📚  Swagger 적용 과정 요약

✅ springdoc-openapi  의존성 추가
✅ @Operation, @Parameter 등을 활용하여 API 문서화
✅ Swagger UI에서 API 테스트 (/swagger-ui)
✅ application.yml에서 Swagger 설정 변경 가능
✅ Spring Security 설정을 추가하여 접근 제한 가능

🚀 Swagger를 활용하면 API를 보다 체계적으로 관리할 수 있으며, 개발자 간의 협업도 용이해집니다.