[Spring Boot] Spring Boot에 Swagger 추가하기

 Swagger는 개발자가 자동으로 REST API를 문서화할 수 있게 도와주는 오픈소스 프레임워크이다.

 

 백엔드에서 개발한 서버 API를 프론트엔드에서 연결해야 하는데, 문서화를 해두면 API를 쉽게 파악할 수 있어 협업하는 데 좋다. 그리고 Swagger 같은 경우에는 간단한 테스트를 할 수 있는 UI도 제공하여 API 테스트를 하기에도 좋다.

 

 

 

 

 

 그동안 프로젝트를 진행하며, 서버 API를 문서화를 위해 Swagger를 사용했었다. 작년에 Spring Boot 2.X 버전에서 개발하며 Springfox를 적용해 Swagger를 추가했었는데, 이번에 Spring 3.X 버전에서 개발하며 Springfox가 적용되지 않는 문제를 발견했다.

 

 Springdoc을 적용하면 해결할 수 있다는데, 두 라이브러리의 차이에 대해 알아보고 Swagger를 적용하고자 글을 쓰게 되었다!

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Swagger를 구현할 수 있는 라이브러리로는 크게 Springfox와 Springdoc 두 가지가 있다. 

 

 

 

 

 

 

Springfox

---

자동으로 Spring에서 JSON API를 문서화해주는 라이브러리이다. 2020년 10월을 마지막으로 `3.0.0`에서 업데이트가 멈췄다. (깃허브에 들어가면 확인할 수 있다.)

 

• 공식 문서 : https://springfox.github.io/springfox/docs/current/

 

 

 결론적으로 말하자면, Spring Boot 2.X 버전에서는 적용이 되나, Spring Boot 3.X 버전에서는 적용이 되지 않는다. 시기를 보면 그럴 것이 Spring Boot 3.0 버전은 2022년 11월에 릴리즈 되었다.

 

 

 

 

Dependency

dependencies {
    implementation group: 'io.springfox', name: 'springfox-boot-starter', version: '3.0.0'
}

 

`springfox-boot-starter` 의존성을 추가해주면 된다.

 

 

 

 

 

Springdoc

---

 Spring Boot 프로젝트에 자동적으로 API를 문서화 해주는 자바 라이브러리이다. 런타임 시, Spring 설정과 클래스, 어노테이션을 읽어서 이를 바탕으로 API 문서를 만든다.

 

아직까지 활발히 업데이트 되고 있으며, Spring Boot 3를 지원한다.

 

 

• 공식 문서 : https://springdoc.org/

 

출처 : https://springdoc.org/

 

 

Springdoc은 다음과 같은 구조로 이루어져 있다. Springdoc은 Spirng WebMvc와 WebFlux를 지원한다.

 

Spring Web을 쓴다면 `springdoc-openapi-starter-webmvc-api`의존성을 추가하고,

Spring WebFlux를 쓴다면 `springdoc-openapi-starter-webflux-api`를 추가하면 된다.

 

`springdoc-openapi-starter-webmvc-api`와 `springdoc-openapi-starter-webmvc-ui`의 차이점으로는 시각화에 있다.

api는 OpenAPI 문서를 생성하고, ui는 OpenAPI 문서를 보여줄 수 있는 UI를 제공한다.

 

 

 

 

Dependency

dependencies {
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
}

 

 

 

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

 

 

 

서버와 ip와 포트번호를 맞게 입력하고, 해당 주소로 접속하면 Swagger UI 페이지가 뜬다.

SwaggerConfig를 구현하지 않아도 기본적으로 프로젝트 내의 Controller의 어노테이션을 분석해서 자동적으로 API를 시각화해준다.

 

 

 

 

 

 

 

 

 하지만 좀 더 자세한 API 명세가 필요하다면, SwaggerConfig를 추가해 Controller와 Entity, Dto 클래스에 별도의 Swagger 어노테이션을 붙이면 된다. 그러면 커스텀 Swagger UI를 만들 수 있다.