[SpringBoot] Swagger 적용

이번 프로젝트는 백엔드를 내가 맡고 프론트엔드는 다른 친구가 개발하는 프로젝트이기에 API 문서 정리가 필요했다.

 

그 외에도 프로젝트 목표 달성 이후에도 계속 이어지는 서비스를 개발하고자 했기 때문에

 

이후에 내가 팀을 나오게 되더라도 후임 개발자가 서비스의 유지보수 및 추가기능 개발을 하는데 있어서도 도움을 주고자

 

Swagger를 이용해 프로젝트 초기부터 API 문서를 정리하기로 했다.

 

 

 

Swagger - 스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

 

출처 - 위키백과 (https://ko.wikipedia.org/wiki/%EC%8A%A4%EC%9B%A8%EA%B1%B0_(%EC%86%8C%ED%94%84%ED%8A%B8%EC%9B%A8%EC%96%B4)

스웨거 (소프트웨어) - 위키백과, 우리 모두의 백과사전

 

 

 

먼저 의존성 추가를 위해 maven repository에서 springfox를 검색해 Springfox Swagger2와 Springfox Swagger UI를 가져온다.

 

현재 2020.08.10 기준 3.0.0 버전이 최신 버전이지만 usage수가 높은 2.9.2버전을 선택한다.

 

 

 

 

gradle 기반 프로젝트이므로 gradle 의존성을 복사해와 build.gradle에 추가해준다.

 

 

 

 

현재까지 어노테이션을 이용해 Bean을 관리해왔으므로 이 프로젝트에서는 처음으로 config 파일을 생성한다.

 

이후에 config 파일 활용을 추가로 공부해 코드를 변경할 예정이므로 config 패키지를 추가해 관리해주도록 하자.

 

Swagger관련 설정을 Spring Boot에 맡기기 위해 SwaggerConfig 자바파일을 생성해준다.

 

 

 

 

API 문서를 생성하므로 API별 설정을 해주어야 한다. Controller로 가서 API별로 어노테이션을 이용해 설정해준다.

 

 

 

@ApiOperation 어노테이션을 이용해 API의 이름과 설명을 달아준다.

 

@ApiImplicitParams 어노테이션과 @ApiImplicitParam 어노테이션을 이용해 API의 파라미터들을 보여준다.

 

@ApiResponses 어노테이션과 @ApiResponse 어노테이션을 이용해 리턴되는 Response에 대해서도 제어를 할 수 있다.

 

 

 

 

이제 애플리케이션을 로컬에서 구동 후 http://localhost:8080/swagger-ui.html 로 접속하면

 

다음과 같이 API 문서가 생성된 것을 확인할 수 있다.

 

 

 

추가로 다른 셋팅들은 필요하게 되면 그때그때 적용하는 것으로 정하고 Spring boot 프로젝트에 Swagger 연동을 마쳤다.