[Spring] Swagger에 대해서

Swager는 RESTful API를 설계, 빌드, 문서화, 테스트 할 수 있는 오픈 소스이다. API 개발자와 소비자 간의 의사소통을 원활하게 하며, API 사용방법을 이해하기 쉽게 해준다. Spring Framework에서도 이를 활용해 API를 문서화 할 수 있다. Spring Framework는 Spring Boot와 달리 수동으로 더 많은 설정을 해주어야 한다.

---

Spring에서 Swagger 설정하기

SpringFox 라이브러리를 사용하여 Swagger를 통할 할 수 있다.

1. Maven 의존성 추가

pom.xml 파일에 Swaager와 관련된 SpringFox 의존성을 추가 한다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. Config Class 생성

Swagger 설정하기 위한 Java Configuration class를 작성. @Confuguration 어노테이션을 사용하여 Swagger 설정 정의

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // API 문서를 생성할 패키지 지정
                .paths(PathSelectors.any())
                .build();
    }
}

 

3. Web MVC Configurer 설정

리소스 핸들러를 추가해 줘야한다. 이를 위해 WebMvcConfigurer를 구현하거나 XML 설정을 사용할 수 있다.

WebMvcConfugurer 설정

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

XML 설정

<bean class="springfox.documentation.spring.web.plugins.Docket">
    <constructor-arg name="documentationType" value="SWAGGER_2"/>
    <property name="select" ref="apiSelectorBuilder"/>
</bean>

<bean id="apiSelectorBuilder" class="springfox.documentation.builders.ApiSelectorBuilder">
    <constructor-arg ref="docket"/>
    <property name="apis" value="RequestHandlerSelectors.basePackage('com.example.controller')"/>
    <property name="paths" value="PathSelectors.any()"/>
</bean>

4. Swagger UI 접근

설정이 완료되면, localhost:8080/swagger-ui.html 에 접속하여 Swagger UI에 접근할 수있다. 이 UI는 모든 API 엔드포인트와 해당하는 메소드, 요청 파라미터, 응답 형식 등을 시각적으로 보여 준다.

5. Swagger를 사용한 API 문서화의 장점

• 자동 문서화: API를 추가하거나 수정할 때마다 문서가 자동으로 업데이트되어, API 문서의 일관성을 유지할 수 있다.
• 인터랙티브 테스트: Swagger UI를 통해 API 엔드포인트를 직접 테스트할 수 있다.
• 명확한 API 정의: Swagger는 API의 입력과 출력, 메소드 설명 등을 명확하게 정의하므로, 개발자와 API 소비자 간의 의사도통이 원활해진다.
•  

---