Spring Boot 3 + Swagger 3 연동해 보기
서론
사실 난 swagger가 뭔지 모른다.
대략 RESTAPI를 개발할때 서버(백엔드)와 클라이언트(프론트엔드)간 프로토콜 동기화를 위해 강력하게, 유용하게, 자주 사용된다는 정도밖에 모른다.
그리고 공부를 해 보려 해도 도대체 감이 잡히질 않았다.
그래서 설치해서 사용해 보기로 했다.
그런데 Spring Boot 3와 Swagger 3가 비교적 최신 버전이라서,
Reference를 찾기가 힘들었다.
이렇게 하는게 맞나 싶지만,
어째저째 index.html은 띄웠기에 기록을 해 둔다.
제약
나는 IntelliJ IDEA Community Edition을 사용하고 있기에, 유료인 Ultimate 버전과 달리 Spring Boot를 직접 생성할 수 없었다.
번거롭긴 하지만 Spring Initializr 라는 사이트에서 초기 Framework를 Generate해서 다운로드 받는 방법이 가장 Quick & Easy 한 방법 인것 같다.
Spring Boot 3 초기 코드
위 사이트에 들어가서 아래와 같이 설정 해 준다.
- Project의 Build도구로 Gradle과 Maven을 선택할 수 있는데, 이것은 개인의 취향 차이 이므로 선호하는 것을 골라준다.
- Spring Boot는 현재 릴리즈된 버전중 안정화 된 버전이 3.0.6이다. 각종 영어가 붙어있는 버전은 개발중인 버전이다.
- Java 버전은 17을 사용해야 한다.
Spring Boot 3 부터는 17이 필수라 한다.
우측에 "ADD DEPENDENCIES"를 눌러 "Spring Web"을 찾아 선택해 준다.
Lombok은 Java의 Annotation Library라고 하는데,
대표적인 annotation은 "@Override"가 있다.
즉, @뒤에 기능을 특정하는 역할을 하는 것이 annotation인것 같다.
Lombok이 뭔지 잘 모르겠으나 여러 사람들이 사용하는것 같다. 그래서 나도 일단 써본다.
이제 하단에 "GENERATE" 버튼을 클릭하여 지금까지 설정한 내용을 소스코드로 받는다.
위와 같은 경우에는 myswagger.zip 파일로 받아졌다.
여기까지 작업한 내용은 Spring Boot 3.0.6을 이용하여 초기 틀만 잡은것이다.
Swagger는 추후에 Gradle에서 추가해 준다.
소스적용
위 절차에서 다운로드 받은 myswagger.zip 파일을 IntelliJ IDEA의 workspace에 복사하고 압축을 푼다.
본인의 경우에는 WSL2에 환경을 꾸몄으므로 그곳에 압축을 푼다.
압축을 풀고 프로젝트를 Open 하자 마자 부터 에러가 발생한다.
에러의 내용으로 봐서 윈도우즈에 설치된 Java를 이용하여 gradle 빌드를 하려해서 그런것 같다.
- Project Structure 설정에서 Project 탭에 SDK를 WSL에 Java로 선택하고, Language level을 SDK default로 설정한다.
- Settings의 "Build, Execution, Deployment" 탭 - Build Tools - Gradle - Gradle JVM에 "Project SDK"를 선택한다. 혹은 WSL의 JAVA 버전을 선택한다. 17이 될것이다.
Apply와 OK를 눌러 저장을 한다.
이제 gradle을 빌드 할 차례이다.
좌측 'Project' 탭에서 'build.gradle' 파일을 열고 gradle build를 위해 아래 단축키를 누르자.
- Ctrl + Shift + O
단축키 환경은 사람마다 다를 수 있는데.. 단축키 말고 다른 방법은 잘 모르겠다.
그저 build.gradle 파일에 변경이 일어나면 우측 상단에 작은 코끼리 모양 아이콘이 뜨는데 그것을 눌러도 된다.
gradle 빌드가 끝나면 위와 같이 빨간색 글씨가 없는 깨끗한 화면이 보이게 된다.
지금까지의 과정은 '소스코드'를 빌드한것이 아니라,
내가 사용하고자 하는 외부의 dependency들을 가져와서(다운로드 받아서) 프로젝트 내에 포함시키는 작업을 자동으로 해주는 작업 이었다.
이제는 swagger dependency를 추가하고 프로젝트내에 에러 없이 포함 시키는 작업을 진행 해야 한다.
Swagger 3 연동하기
짐작컨데 build 환경을 자동으로 꾸려주는 툴은 Maven이 먼저 만들어지지 않았나 싶다.
그렇게 생각한 이유는 Dependency의 Repository가 거의 모두 maven을 향해 있기 때문이다.
본인은 gradle을 선호 하지만 build.gradle 파일안에는 repositories로 'mavenCentral()'이 있을 정도다.
앞으로도 Java와 연동이 필요한 Dependency(혹은 External Library)가 존재하는지, 최신 버전은 몇인지, 어떻게 적용해야 하는지 등을 알고 싶을때는 아래 사이트에 접속하여 관련 정보를 찾아 보면된다.
우리가 사용하는 Spring Boot 3.0.6 버전과 연동되는 Swagger의 dependency에 변동이 있다고 한다. 기존에 사용하던 springfox가 아닌 springdoc에서 제공 한다고 한다.
io.springfox:springfox-swagger2:3.0.0 (X)
(Spring Boot 2.x 에서 Swagger 3.0을 사용할때)org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0 (O)
(Spring Boot 3.x 에서 Swagger를 사용할때)
그럼, Spring Boot3과 Swagger 3은 합쳐질 수 없는 조합인가?
그건 잠시 후에 확인 해 보자.
다시, 위에 Mavel Central 사이트에서 우리가 사용할 springdoc-openapi-starter-webmvc-ui를 가져다 쓰려면 어떻게 해야 하는지 확인 해 보자.
확인 결과 현재는 2.1.0 버전이 최신 임을 알 수 있다.
View all을 클릭해서 보이는 Table에서 최신 버전의 Row끝에 있는 '>'를 클릭해 보자.
위와 같이 Snippets이 나오는데 ComboBox를 이용하여 본인의 Build 환경에 맞게 선택하여 클립보드에 복사가 가능하다.
실행
지금까지 우리는 소스의 주변 환경만을 수정했을 뿐,
소스 코드 자체는 수정하지 않았다.
하지만 마치 Hello World 처럼 컴파일 하여 실행을 할 수 있다.
실행을 위해서는 src 폴더를 타고 내려가서 'MyswaggerApplication'(.java) 파일을 열어야 한다.
그 파일을 연 상태로 우측 상단에 있는 재생 버튼을 누르면 컴파일 후에 자동으로 실행이 된다.
실행이 되었다면 정지 버튼이 보이고 하단 'Run' 탭에는 위와 같이 보이게 될 것이다.
이제, 같은 컴퓨터에 있는 웹 브라우저를 열어서 아래와 같이 입력한다.
뭔가 내용이 들어있지는 않지만, Hello World 치고는 대단히 있어보이는 UI 화면이다.
위와 같은 화면이 보였다면 설치와 연동이 완료 된 것이다.
추가로 우측 상단에 보면 OAS3 이라는 아이콘이 보이고, 좌측 상단에는 Swagger라는 이름이 보인다.
OAS는 Open Api Specification의 약자로서 RESTful 프로토콜 사용을 위한 사양을 정의하는 규격인것 같다. 그리고 그 규격에 맞추어 framework를 만든게 Swagger로 보여진다. SpringDoc은 Swagger를 사용하기 편하게 해주는 도구로 짐작 된다.
따라서 우리는 Spring Boot 3 와 Swagger 3를 연동한 것이다.
마무리
설치는 했지만.. 어떻게 쓸지 모르겠다. 더 공부를 해야 하고, 더 짜투리 시간을 내야 한다.
어쩌면 이 설치/연동 과정도 잘못되어 다시 개선해야 할 필요도 있을 것이다.
머.. 항상 그렇듯이.. 삽질의 연속이니까.. 그러려니 하고.. 앞으로 어떻게 api를 꾸려나가야 할지를 좀더 파고 들어 봐야 겠다.
댓글
댓글 쓰기