[Spring] Spring 3.x + Swagger 설정

Spring 3.x 프로젝트 환경을 설정하며 API 문서로 Swagger 를 사용하려고 하는데 그 전에 비해 방법이 더 간단해져 정리해보았다.

 

---

Swagger 란 ?

Swagger 는 REST API 를 설명하고 문서화하는 데 사용되며, OpenAPI 사양을 기반으로 구축된 오픈 소스 프레임워크이다. 공식 문서에 따라 OpenAPI 사양은 REST API 에 대한 API 설명 형식으로 아래를 포함한 전체 API 를 설명할 수 있다.

- 사용 가능한 엔드포인트(/users) 및 각 엔드포인트의 작업 ( GET /users, POST /users )
- 작업 매개변수 각 작업에 대한 입력 및 출력
- 인증 방법
- 연락처 정보, 라이센스, 이용 약관 및 기타 정보

 

---

Swagger 적용하기

spring boot 3.x 에 swagger 를 적용하는 방법은 굉장히 간단하다. 따로 config 파일을 만들 필요 없이 라이브러리를 추가하고 http://server:port/context-path/swagger-ui.html 로 접속하면 확인이 가능하다. 

 

1. 라이브러리 추가 ( Gradle ) 

// Swagger 설정
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

위의 라이브러리 기능은 다음과 같다.

- 자동 API 문서화 : spring boot 의 컨트롤러, 서비스 및 모델을 기반으로 API 문서를 자동 생성한다.

- Swagger UI 통합 : Swagger UI 를 자동으로 통합하여, 개발자가 웹 브라우저를 통해 API 문서를 쉽게 볼 수 있도록 해준다. 이를 통해 API 엔드포인트를 시험해보고 실제 요청을 보내 응답을 확인할 수 있다.

- 사용자 정의 및 확장성 : 개발자는 라이브러리 설정을 조정하여 API 문서의 세부 사항을 사용자 정의할 수 있다.

 

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

 

---

발생 이슈

라이브러리를 추가하고 서버를 띄웠을 때 NoProviderFoundException 이 발생했었다.

주요 이유는 Jakarta Bean Validation 이 클래스 패스에 없기 때문으로, Spring boot 3.x 는 Jakarta EE의 새로운 네임스페이스를 사용하는데 이로 인해 기존의 Swagger 가 호환되지 않는 문제가 발생할 수 있다고 한다.

 

해결 방법은 Jakarta Valitadion API 를 의존성에 추가하는 것이다. 

implementation 'org.springframework.boot:spring-boot-starter-validation'

 

---

참고

https://swagger.io/docs/specification/about/

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oasDocument

https://springdoc.org/

https://dev.to/runtycybin/openapi-spring-3-noproviderfoundexception-58oh