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://dev.to/runtycybin/openapi-spring-3-noproviderfoundexception-58oh
'Web' 카테고리의 다른 글
| [Spring] RestTemplate 과 WebClient (0) | 2023.12.03 |
|---|---|
| [Spring] Swagger 에 JWT 설정하기 (0) | 2023.11.26 |
| [System Design] URL 단축기 설계 -1 (0) | 2023.11.05 |
| [Spring] Transaction 에 대해서 (3) | 2023.10.22 |
| [JPA] 지연로딩과 즉시로딩 (0) | 2023.10.08 |