스프링부트로 게시판 만들기 12(完) : API 문서 생성 자동화

개요

이번 포스팅에서는, Swagger를 이용해서 REST API 문서를 자동으로 생성하는 법을 다루려고 한다.

​
​
​
​

문서화의 중요성

한가지 상황을 가정해보도록 하자.

​
​

만약 여러분이 프론트 개발자, 다른 팀에서 만들어진 REST API를 사용 해야하는 입장의 개발자라고 가정을 해보자.

이때, 프로젝트가 다 됬다고 듣고, API를 사용하려고 봤는데 어떻게 사용하는지에 대한 메뉴얼을 주지 않아서 사용방법을 알아내기 위해 저 API를 개발한 직원을 직접 부르거나 여러분이 직접 저 코드들을 분석해서 사용방법을 알아내느라 1~2주가 소요 되어버렸다. 상상만 해도 정말 끔찍하다.

이런 상황을 어떻게 극복하면 좋을까?

​

​

​

​

위와 같은 상황을 방지해주기 위해, 저러한 API를 만들고 나서는 API 문서를 만들어주는것이 필수이다.

​

하지만, 일일히 저러한 API를 직접 적어주는것은 너무나도 귀찮다. 이걸 자동화 하는 방법은 없을까?

​

다행히 스프링에서는 (사실 어지간한 다른 프레임워크에서도) Swagger 라는 API 문서를 자동으로 만들어주는 도구를 가지고 있다.

​

이제 이걸 사용하는 방법을 알아보도록 하자.

(여담으로, swagger 플러그인들을 이용하면 JMeter와 같은 부하테스트 스크립트를 자동으로 만들어 줄수도 있어서 나중에 부하테스트도 손쉽게 할 수 있다)

​

​

##Swagger 연동

​

먼저 maven에 아래 라이브러리들을 포함시켜주자.

​

<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>

​

그리고 나서, 아래와 같이 Config 파일을 작성 해주자.

​

import com.google.common.base.Predicates;
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(Predicates.not(RequestHandlerSelectors.
                    basePackage("org.springframework.boot")))
            .paths(PathSelectors.any()).build();
    }
}

​

​

이제, 실행을 시켜보도록 하자.

​

​

테스트

​

일단, 문서를 보기 위해서는 단순하게 아래 URL에 들어가면 된다.

http://localhost:8080/swagger-ui.html#/
​
​
​
​
그러면 아래와 같은 화면을 볼 수 있다.

​
​
​

​
​
​
​

​

결론

​

이제 기본적인 작업은 거의다 끝이 나기는 했다. 사실, 이번 강좌 같은 경우에는 기능추가 라기 보다는 Swagger와 같은 API 문서를 자동화 해주는 걸 알려주고 싶어서 넣은 면도 있다.

​

이제 남은 기능은 아래와 같다.

• 관리자 페이지
• 리팩토링
• 유닛테스트 추가
• 프론트엔드 작업
• OAuth
• 기타 부가기능(레벨 기능, 비밀글, 권한 등등)

​

사실 위의 것도 후속강의로 포스팅을 하면 좋겠으나, 일단은 여기서 마치도록 하겠다.

나머지 부분은 여러분들의 과제로 남겨두도록 하겠다...

​

지금까지 봐주셔서 감사합니다.

​

​

p.s

​

지금까지 봐주셔서 감사합니다.

다음 포스팅은 다른 프로젝트로 찾아뵙도록 하겠습니다.

프론트와 같은 경우, 나중에 리액트 포스팅을 하면서 진행을 할 수 는 있을것 같다..