BAEKJH BE Developer

스프링부트 Swagger 설정하기

2020-12-24
BAEKJungHo

logo

서론

스프링 부트에서 API 의 관리 및 테스트를 가능하게하는 오픈소스인 Swagger 설정 방법에 대해서 알아봅시다.

Swagger 란?

개발을 하다보면 해당 API 서버가 어떠한 데이터를 주고 받고, 어떠한 스펙을 가지는지 문서 및 테스트가 필요한데, Swagger 는 이를 가능하게 합니다. 즉, API Spec 에 관한 문서화를 자동으로 해줍니다.

Swagger vs Spring Rest Docs

  • Swagger 의 장점
    • 테스트 코드를 작성하고 테스트를 성공시켜야 만들어지는 Spring REST Docs 와 달리 Swagger 는 코드 몇 줄만 추가하면 만들 수 있다.
    • 테스트할 수 있는 UI 를 제공한다.
    • Spring REST Docs 는 테스트를 돌리면서 성공하는 지 실패하는 지 확인했지만 Swagger 는 문서 화면에서 API 를 바로바로 테스트할 수 있다.
  • Swagger 의 단점
    • 자바 코드에 어노테이션을 추가해야한다.
    • 자바 코드와 동기화가 안될 수도 있다.

Swagger 설정 하기

Maven 을 기준으로 설명합니다.

의존성 추가

Maven Repository springfox-swagger2

  • swagger 를 사용하기 위한 의존성
  • swagger ui(화면)와 관련된 의존성
<!-- springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

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

resourceHandler 설정

css, image 파일 같은 정적 파일 자원을 스프링에서는 <mvc:resources> 를 이용해서 매핑 해줘야 View 단에서 제대로 정적 파일을 찾을 수 있는데, 스프링 부트는 spring-boot-starter-web 에서 알아서 처리해줍니다.

그 외의 경로에 있는 정적 파일을 사용하기 위해서는 추가 설정이 필요한데, 만약에 jar 안에 있는 경로나, 클래스 경로 등에 대해서 정적 파일을 사용하기 위해서는 등록을 해줘야 합니다.

WebMvcConfigurerAdapter 를 상속받은 WebConfig 클래스에서 addResourceHandlers 를 오버라이딩하여 구현하면 됩니다.

ResourceHandlerRegistry

웹 브라우저에서 효율적인 로딩을 위해 최적화 된 캐시 헤더 설정을 포함하여 Spring MVC를 통해 이미지, CSS 파일 등의 정적 리소스를 제공하기위한 리소스 핸들러의 등록을 저장합니다. 리소스는 웹 애플리케이션 루트 아래의 위치, 클래스 경로 및 기타 위치에서 제공 될 수 있습니다.

    @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/");
    }

Swagger2(2.9.x) 를 사용하는 경우 swagger-ui.html 에 접근하면 404 Not Found 에러가 발생하는 경우가 있습니다. 이러한 경우 스프링 부트의 WebConfig 에서 ResourceHandler 에 swagger-ui.html 페이지가 어디에 있는지 위치를 추가해야 합니다.

SwaggerConfig 생성

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Weave")
                .description("API 테스트 및 관리")
                .build();
    }

    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Weave")
                .apiInfo(this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/**/api/**"))
                .build();
    }

}

특정 패키지 지정하기 : .apis(RequestHandlerSelectors.basePackage("com.weave.*.*.*.web.rest"))

  • Swagger 설정을 정의한 코드
  • .consume() 과 .produces() 는 각각 Request Content-Type, Response Content-Type 에 대한 설정(선택)
  • .apiInfo() 는 Swagger API 문서에 대한 설명을 표기하는 메소드 (선택)
  • .apis() 는 Swagger API 문서로 만들기 원하는 basePackage 경로 (필수)
  • .path() 는 URL 경로를 지정하여 해당 URL에 해당하는 요청만 Swagger API 문서로 만든다. (필수)

설정이 다 끝났으면 접속 방법은 다음과 같습니다.

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

@Profile

  • @Profile
  • 로컬과 개발환경에서는 Swagger 를 활성화 시키고, 운영 프로파일에서는 Swagger 설정이 적용되지 않도록 처리 가능

Swagger 구성을 별도의 구성 클래스에 넣고 @Profile 을 달아 특정 프로필에서만 Spring 컨텍스트로 스캔되도록해야합니다.

@Configuration
@EnableSwagger2
@Profile({"local", "dev"})
public class SwaggerConfig {
    // your swagger configuration
}
  • application.properties
spring.profiles.active=dev
  • application.yml
spring:
    profiles:
        active: local

참고

  • https://jojoldu.tistory.com/31
  • https://velog.io/@tigger/API-%EB%AC%B8%EC%84%9C-%EC%9E%90%EB%8F%99%ED%99%94-Swagger
  • https://woowabros.github.io/experience/2018/12/28/spring-rest-docs.html

Similar Posts

Comments