Swagger (Springfox)를 이용해 스프링 프로젝트의 API 문서 만들어보기

보통 실무에서 개발은 혼자 하는 것이 아니라 팀을 이루어서 협업으로 진행되게 된다.

백엔드가 만들어 놓은 API를 프론트엔드가 알아야 하는데 API를 만들고 수정할때마다 카톡으로 공유할 수는 없는 노릇이다.

 

이런 문제를 해결하기 위해 등장한 것이 Swagger 되겠다.

 

 

아이콘부터 뭔가 있어보이게 생겼다. 

 

Swagger 공식 홈페이지를 들어가니까 SwaggerHub 으로 연결되길래 Swagger가 없어지고 또 SwaggerHub로 바뀐건가? 싶었는데 그런건 아니었다.

 

근데 Swagger 홈페이지에 들어가서 공식 API 문서를 찾아보려고 하는데 한참 봐도 Getting Started 항목이 안보이는 것이었다. 검색창에 gradle 쳐보니까 그제서야 자바와 관련된 뭐가 떠서 찾아보니

 

Swagger API를 지원하는 Ecosystem이 있는데, 그 중에서 자바 언어를 지원하는 라이브러리를 내가 하나 골라서 사용하면 되는 것이었다. 그니까 Swagger라는 오픈 API를 구현한 구현체를 골라서 사용하면 되는 것이다.

 

이거 마치 JPA와 하이버네이트의 관계 같은 그런 느낌이다.

 

Java Integration | Swagger Open Source

 

위 사이트에 들어가면 Java Integration을 지원하는 라이브러리들이 많이 있다.

swagger-core, swagger-parser 이 둘은 Swagger API 명세를 작성한 그룹이 만든 검증된 라이브러리인 것 같고,

이외에 일반 Community-Driven 라이브러리 중에서 springfox가 대표적으로 보였다.

 

 

mavenRepository에 가서 swagger 이용 순위를 보니 다른 라이브러리에 비해 springfox가 압도적으로 많았다.

역시 괜히 국내 블로그들에서 springfox만 사용하는 것이 아니었다. 다수가 이용하는 걸 사용하면 실패는 안한다.

 

이제 Swagger API를 구현한 구현체인 Springfox를 이용해 API 문서를 만들어 보자

공식 레퍼런스를 읽는 힘을 기르기 위해 국내 블로그는 최대한 보지 않고 진행해보려고 한다!  하였으나.. 좀 힘들어서 참고를 할수밖에 없었다....;;; 공식 문서에는 내가 굳이 필요없는 내용까지도 일단 전부 포함해두고 있으니 내가 꼭 필요한 것만 뽑아서 적용하는것 부터가 쉽지않았다. ㅜ 

 

Springfox Reference Documentation

 

1. build.gradle에 springfox-boot-starter 의존성 추가

(스프링 부트 프로젝트에서만 가능 - 추가하면 연관 라이브러리들까지 한방에 다 가져와주니 편리하다)

implementation "io.springfox:springfox-boot-starter:3.0.0"

 

 

2. Configuration 파일 추가

// 연결 링크 >>> http://localhost:8080/swagger-ui/index.html
@EnableSwagger2 // Enables Springfox swagger 2
@Configuration
public class SwaggerConfig {

    // Docket: Springfox's primary api configuration mechanism
    @Bean
    public Docket myApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select() // returns an instance of ApiSelectorBuilder to give fine grained control over the endpoints exposed via swagger.
                .apis(RequestHandlerSelectors.basePackage("[기준 패키지 경로]")) // 해당 패키지 이하에 있는 api만 보겠다.
                .paths(PathSelectors.ant("/api/**")) // 해당 경로로 요청하는 api만 보겠다
                .build() // The selector needs to be built after configuring the api and path selectors.
                .useDefaultResponseMessages(false)
                .apiInfo(customApiInfo());
    }

    private ApiInfo customApiInfo() {
        return new ApiInfoBuilder()
                .title("[제목]")
                .description("[설명]")
                .version("[버전]")
                .contact(new Contact("[내 아이디]", "[내 소개]", "[이메일]"))
                .build();
    }
}

 

3. 실행!!

 

** Failed to start bean 'documentationPluginsBootstrapper' 발생하는 경우 **

- application.properties에 아래와 같은 설정을 추가한다. 버전에 따른 문제라고 한다.

# Swagger 설정
spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

http://localhost:8080/swagger-ui/index.html 접속

 

 

 

오

뭔가 정말 전문적인 개발을 하는 것 같은 느낌이다.

 

 

심지어 단순히 무슨 API가 있는지를 볼 수 있는 것 뿐만 아니라, 해당 API로 요청을 날리고 응답까지도 받아볼 수 있다.

Postman 역할을 웹으로도 할 수 있다는 것!

 

실제 API를 수행해본 결과

 

이제 팀원들 끼리 Swagger를 이용해 API 정보를 효과적으로 공유할 수 있게 되었다

 

열심히 개발해보자!!