Spring Boot에서 Springdoc-OpenAPI로 API 문서 자동화하기

Springdoc-OpenAPI를 활용한 Spring Boot 기반 API 문서 자동화

안녕하세요! 프로그래밍에 열정을 가지고 계신 여러분, 오늘은 Spring Boot 프로젝트에서 API 문서화를 자동으로 처리할 수 있는 Springdoc-OpenAPI에 대해 알아보겠습니다. API의 문서화는 팀원 간의 원활한 소통과 협업을 위한 필수적인 과정이며, 자동화 시스템을 구축함으로써 한층 더 효율성을 높일 수 있습니다. 이 포스트에서는 단계별로 설정 및 활용 방법을 안내해 드리겠습니다.

시작하기에 앞서

오늘의 주제는 OpenAPI Specification를 기반으로 한 API 문서화입니다. RESTful API를 사용하는 서비스가 늘어남에 따라 명확한 문서화의 필요성이 더욱 커졌습니다. Springdoc-OpenAPI는 이러한 요구를 충족하기 위해 Spring Boot 환경에서 쉽게 설정할 수 있는 Java 라이브러리입니다.

1. Springdoc-OpenAPI 소개

Springdoc-OpenAPI는 Swagger-ui를 내장하고 있어, API 문서 생성 및 테스트를 편리하게 할 수 있습니다. Spring Boot 프로젝트에 의존성 추가와 간단한 설정만으로 사용할 수 있으며, API에 대한 정보를 손쉽게 시각화해줍니다.

2. 의존성 추가하기

먼저 build.gradle 파일에 필요한 의존성을 추가해 주세요.

dependencies {
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.11'
    // 기타 의존성
}

이렇게 하면 Springdoc-OpenAPI를 프로젝트에서 사용할 수 있습니다.

3. 기본적인 프로젝트 구성

Spring Boot Web 프로젝트를 생성한 후, 다음과 같은 기본적인 설정을 해주겠습니다.

application.yml

spring:
  application:
    name: SpringDocExample
server:
  port: 8080

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

위 설정은 Swagger UI와 OpenAPI 문서 생성을 활성화하는 기능을 포함하고 있습니다.

4. HomeController 생성하기

이제 API를 위한 컨트롤러를 작성해 보겠습니다.

@RestController
public class HomeController {

    @GetMapping("/")
    public ResponseEntity<String> home() {
        return ResponseEntity.ok("OK");
    }
}

HomeController는 기본적인 건강 체크 API로, 시스템이 정상 작동 중임을 나타냅니다.

5. API 문서화 설정

API 정보를 세부적으로 정의하기 위해 다음과 같은 클래스를 생성합니다.

@OpenAPIDefinition(
    info = @Info(
        title = "Spring Doc Example API Document",
        description = "API Document",
        version = "v0.1"
    )
)
@Configuration
public class SpringDocConfig {}

이제 Swagger UI에 접속하면 API 문서화된 정보를 볼 수 있습니다. 기본적으로 http://localhost:8080/swagger-ui/index.html에서 접근할 수 있습니다.

6. 보안 설정 적용하기

Schwangdoc-openapi에서는 인증과 관련된 기능을 지원합니다. 여기서는 JWT를 사용하는 예를 들어보겠습니다.

의존성에 보안 관련 라이브러리를 추가합니다.

implementation 'org.springframework.boot:spring-boot-starter-security'

SecurityConfig 클래스를 생성하여 API 접근을 보호하고 보안 전략을 설정합니다.

@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http.csrf().disable()
                .authorizeRequests()
                .antMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll()
                .anyRequest().authenticated()
                .and()
                .build();
    }
}

위 코드는 문서에 접근할 수 있는 경로를 공개하고, 나머지 API는 인증이 필요하다는 것을 의미합니다.

이제 springdoc 설정을 통해 JWT와 같은 인증 스키마를 추가할 수 있습니다.

7. 마무리하며

오늘은 Spring Boot에서 Springdoc-OpenAPI를 활용하여 API를 문서화하는 방법을 배워보았습니다. 이러한 방법을 통해 프로젝트에 필요한 문서를 자동으로 생성하고, 개발자 간의 협업을 원활하게 할 수 있습니다.

API 문서화는 단순히 기술적인 필요를 넘어서, 사용자와의 소통을 일본화하는 중요한 요소입니다. 여러분의 개발 프로젝트에 이 코드가 도움이 되길 바랍니다! 궁금한 점이 있는 경우 댓글로 남겨주시면 성심껏 답변해 드리겠습니다.

그럼 다음 포스트에서 뵙겠습니다! 감사합니다!