Spring boot 3.x.x 에서의 Swagger적용 방법 (gradle 기준)

사이드 프로젝트를 진행하는 과정에서 프론트와 백엔드간에 API명세서를 작성해야하는 일이 생겼습니다.

 

해당 글은 Spring boot 3이상을 사용하는 프로젝트에서 Swagger를 도입하는 경우 어떤 라이브러리가 좋은지 공유하는 시간입니다.

 

Swagger를 제공하는 라이브러리 종류에는 springfox 와 springdoc 가 있습니다.

 

둘다 써본 결과 제일 괜찮은 것은 springdoc 인거 같아요~

 

다만 SpringBoot 3이상은 springdoc를 이용하셔야합니다~

 

SpringBoot2와 SpringBoot3 둘다 사이드 프로젝트에 참여하면서 해본 결과 확실히 문서 명세서의 Ui 뿐만 아니라

제공하는 서비스에서도 springfox보다 springdoc가 더 좋다는 것을 느꼈습니다.

그러니 springdoc를 좀 더 선호합니다~

 

나중에 깃허브를 보시게 되면 springfox는 현재 2023 기준 그전 부터 업데이트가 되고 있지 않습니다.

하지만 springdoc는 꾸준히 업데이트가 이루어지고 있는 시점입니다.

 

자 이렇게 springdoc에 대해 더 좋다고 설명했으니 이제 SpringBoot에 적용하는 방법을 말씀드릴게요~

 

1. build.gradle 에 dependency를 추가

https://springdoc.org/v2/ 에서 공식문서로 제공하니 확인해서 가져오시면 됩니다.

(springfox를 주석처리한거 보면 아시겠죠? ^^)

 

2. Swagger 문서 확인

기본적으로 dependency를 받게 되면 그 외 SwaggerConfig를 세팅 해줄 필요가 없습니다.

물론 SwaggerConfig를 선언해서 세부적인 내용을 세팅하여 사용 할 수있습니다.

 

http://localhost:8080/swagger-ui/index.html 에 접속하게 되면 아래와 같이 API 문서를 확인할 수 있습니다.

 

 

 

▶ API 그룹 설정 : @Tag

: API 그룹 설정은 각 Controller 클래스 상단에 작성해준다.

• name : 작성한 Controller 클래스가 보여질 이름을 설정해준다.
• description : 해당 API 그룹이 무엇을 나타내는지 알려준다.
•  

 

▶ API 상세 정보 설정 : @Operation

• summary : 해당 API가 무엇을 위한건지 간단하게 작성
• description : 해당 API가 무엇을 위한건지 상세하게 작성

▶ API 상세 정보 설정 :  @Parameters , @Parameter

• value : parameters로 parameter 를 객체로 묵는 역할
• name : 파라미터의 어떤 변수인지 간단하게 작성
• description : 해당 API가 무엇을 위한건지 상세하게 작성

 

3. 정리

간단하게 나마 Swagger에 대한 내용을 정리해 보았습니다.

Swagger를 SpringBoot3에 적용하시고자 하지만 어떻게 해야 막막하신분들에게 그나마 도움이 되고자 정리하였으니 

참고해주시고 더 정리된 Swagger 정보를 가져올 수 있도록 하겠습니다.

 

감사합니다.