[Swagger] API 문서 자동화하기

junwoo·2022년 7월 2일

Spring

목록 보기

1/2

프로젝트를 진행하며 API 문서화 과정은 필요하다. 클라이언트 측에서 개발을 진행하며 해당 문서를 참고하여 팀의 생산성을 높여줄 수 있고, 나중에 해당 프로젝트를 다시 접하게 될 경우 상당 부분 잊어버릴 것이기 때문에 문서로 남겨둔다면 이를 활용하여 도움을 받을 수 있을 것이다.
하지만 이전 프로젝트 Pocket Trainer를 진행할 때는 일일이 Git Book을 사용하여 API를 정리하다 보니 여러 문제가 생겼다. 그 중 한부분이 수정이 필요할 때이다. 팀 회의를 진행하며 수정 사항이 생기게 되는 경우가 있는데 그러다보면 문서와 실제 구현이 다른 경우도 생겼다. 해당 프로젝트를 진행할 때는 불편함만 느끼며 API 문서를 자동화할 수 있다는 사실을 알지 못했는데, 최근 소마 멘토링을 들으며 Swagger라는 도구를 알게 됐다. 따라서 이번 프로젝트에는 Swagger을 사용하여 API 문서화를 자동으로 하기로 결정했고, 먼저 간단히 알아보고 사용해보는 시간을 가졌다.

왜 Swagger를 사용해야 해?

Swagger은 API 문서를 자동으로 만들어 주어 팀의 생산성을 높여준다.

비슷한 도구로 Spring REST Docs가 있는데 이와 비교하여 Swagger은 다음과 같은 장점이 있다.

적용하기 쉽다.
: 코드 몇 줄만 추가하면 만들 수 있다.
테스트할 수 있는 UI를 제공한다.
: Swagger은 문서 화면에서 API를 바로바로 테스트할 수 있다.

사용법

의존성 추가

Swagger 2.x 버전과 다르게 springfox-boot-starter 하나만 추가하면 하위에 필요한 모든 라이브러리가 포함되어 있다.

이런 에러가 뜬다면, 다음을 추가해주자.

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

/* application.properties */
spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHER

/* application.yml */
spring:
    mvc:
      pathmatch:
            matching-strategy: ant_path_matcher

Configuration 추가

Docket: Swagger 설정의 핵심이 되는 Bean
useDefaultResponseMessages: Swagger 에서 제공해주는 기본 응답 코드 (200, 401, 403, 404). false 로 설정하면 기본 응답 코드를 노출하지 않음
apis: api 스펙이 작성되어 있는 패키지 (Controller) 를 지정
paths: apis 에 있는 API 중 특정 path 를 선택
apiInfo: Swagger UI 로 노출할 정보