Spring Boot에서 Swagger 연동하기: 에러 해결과 설정 가이드

Spring Boot와 Swagger 연동: 에러 해결 및 설정 가이드

안녕하세요, 프로그래밍 애호가 여러분! 오늘은 Spring Boot 프로젝트에서 Swagger를 연동할 때 겪는 다양한 문제들과 그 해결 방법에 대해 자세히 알아보겠습니다. 웹 API 문서화 도구인 Swagger는 개발자들에게 효율적인 API 개발을 지원하지만, 설정 과정에서 오류를 만날 경우 당황하게 마련입니다. 이번 포스트를 통해 이러한 문제를 어떻게 극복할 수 있는지 함께 살펴보도록 하겠습니다.

Swagger 연동의 필요성

Swagger는 RESTful API의 구조와 사용 방법을 명확히 할 수 있는 도구입니다. документация를 자동으로 생성해 주기 때문에, 특히 팀원들과 커뮤니케이션이 필요한 경우 유용합니다. 그러나 Spring Boot와 Swagger의 연동은 몇 가지 설정을 요구합니다. 작은 설정 하나가 큰 에러를 야기할 수 있는 만큼, 주의가 필요합니다.

환경 설정

이번 포스트에서는 Spring Boot 2.7.2와 Swagger 3.0.0 버전을 기준으로 설명합니다. 먼저, Swagger를 연동하기 위한 의존성을 설정해보겠습니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

에러 현상 및 해결 과정

Swagger를 연동한 후 /swagger-ui.html로 접근할 때 페이지가 로드되지 않는 문제가 발생할 수 있습니다. 이 때는 Swagger 관련 리소스가 보안 설정에서 차단되기 때문입니다.

먼저, WebSecurity 설정 파일에서 Swagger 관련 URL을 인증에서 제외해줘야 합니다.

@Override
public void configure(WebSecurity web) throws Exception {
    // Swagger 관련 URL 인증에서 제외
    web.ignoring().antMatchers(
        "/v2/api-docs", "/configuration/ui", 
        "/configuration/security", "/swagger-ui.html", 
        "/webjars/**", "/swagger/**"
    );
}

한편, 3.0.0 버전으로 업그레이드한 경우 spring.mvc.pathmatch.matching-strategy 값을 변경해야 할 수 있습니다.

spring.mvc.pathmatch.matching-strategy=ant-path-matcher

SwaggerConfig 설정

Swagger의 설정을 위한 클래스를 작성해 보겠습니다. 이 클래스에서는 API의 기본 정보 및 전역적인 파라미터를 설정할 수 있습니다.

@Configuration
public class SwaggerConfig {
    private static final String API_NAME = "Sample API";
    private static final String API_VERSION = "1.0";
    private static final String API_DESCRIPTION = "Sample API Documentation";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.api"))
            .paths(PathSelectors.any())
            .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title(API_NAME)
            .version(API_VERSION)
            .description(API_DESCRIPTION)
            .build();
    }
}

결과 확인

이제 모든 설정이 완료되었습니다. http://localhost:8080/swagger-ui/index.html로 접속하여 Swagger UI가 정상적으로 로드되는지 확인해 보세요. 정상적으로 설정이 이루어졌다면 API 명세서가 잘 나타날 것입니다.

마무리하며

이 포스트에서는 Spring Boot와 Swagger를 연동하는 과정에서 발생할 수 있는 다양한 문제를 다루어 보았습니다. API 문서화는 소프트웨어 개발에서 매우 중요하며, Swagger는 이를 훨씬 쉽게 만들어 줍니다. 여러분의 프로젝트에 이 코드와 지침이 도움이 되기를 바랍니다.

여러분도 Swagger를 활용하여 API 문서를 작성해보세요! 궁금한 점이나 추가적인 질문이 있다면 주저하지 말고 댓글로 남겨주세요. 다음 포스트에서 더 유익한 내용으로 찾아뵙겠습니다!