SpringBoot 3.x 버전에서 RestDocs + SwaggerUI 사용하기

이전 개인 프로젝트에서 완벽하게 RestDotcs와 SwaggerUI를 활용한 API 문서를 제작했다.

GiftFunding) RestDocs + Swagger 적용하기(feat. Controller 테스트 코드 작성) (tistory.com)

GiftFunding) RestDocs + Swagger 적용하기(feat. Controller 테스트 코드 작성)

 

이걸 참고해서 이번 프로젝트에서도 적용하려고 했는데 역시역시나 ~ 한 번에 되는 건 없다.

 

달라진 점을 꼽자면 GiftFunding 프로젝트에서는 스프링부트 2.7.17 버전이었고

지금 Petory 프로젝트는 3.3.2 버전이다.

 

적용기를 .... 정리해보겠다 !

 

1. 처음 의존성을 그대로 가져와서 했을 때

• 플러그인

id "com.epages.restdocs-api-spec" version "0.16.4" //restdocs -> openapi
id 'org.hidetake.swagger.generator' version '2.18.2' //openapi -> swaggerUI

 

• 디펜던시

//restdocs
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
//openAPI3
testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.16.4'
//swaggerUI
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.7.0'

 

빌드과정에서는 오류가 없지만 컨트롤러 테스트를 실행시키면 오류가 발생한다.

오류 메세지
java.lang.NoSuchMethodError: 'org.springframework.http.HttpStatus org.springframework.restdocs.operation.OperationResponse.getStatus()'

java.lang.NoClassDefFoundError: org/springframework/restdocs/request/RequestParametersSnippet

 

해당 오류 해결

깃허브의 README.md를 확인해보면 스프링부트 3.x버전부터는 0.17.1 버전 이상을 사용하라고 되어있다.

https://github.com/ePages-de/restdocs-api-spec/blob/master/README.md

 

플러그인과 디펜던시의 restdocs-api-spec 버전을 변경해주었다.

 

Swagger plugin은 아래 깃허브 참고

https://github.com/int128/gradle-swagger-generator-plugin/blob/master/README.md#swagger-ui

플러그인
id 'com.epages.restdocs-api-spec' version '0.18.4' // 0.16.4 -> 0.18.4
id 'org.hidetake.swagger.generator' version '2.19.2'

디펜던시
//restdocs
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
//openAPI3
testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.4' // 0.16.4 -> 0.18.4
//swaggerUI
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.7.0'

 

그랬더니 또 다른 오류 발생 !

 

2. OpenAPI의 버전을 맞춰주고 빌생한 또다른 오류 -> Swagger 의존성 변경

오류 메세지
2024-08-01T04:00:34.417+09:00 ERROR 23056 --- [Petory] [nio-8080-exec-5] c.s.P.exception.GlobalExceptionHandler : org.springframework.web.servlet.resource.NoResourceFoundException : No static resource favicon.ico.

 SwaggerUI가 접속이 안 된다 !

 

생각을 해보면 디펜던시에 작성한 3개의 의존성 중 처음껀 RestDocs로 버전을 명시해주지 않는데 나머지 2개

Openapi와 Swagger 의존성들은 버전을 작성해줘야 한다.

 

1번에서 OpenAPI 의존성을 맞춰주었으니 Swagger 의존성을 맞춰주면 해결될 것 같다.

 

공식문서를 참고해서 SwaggerUI 디펜던시 코드를 변경해주었다.

https://springdoc.org/#getting-started

디펜던시
//restDocs
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
//openAPI3
testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.4'     // 0.16.4 -> 0.18.4
//swaggerUI
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'    //코드 변경

 

그리고 해결 ㅎㅎ

 

application.yml에 적어놓은 /docs/swagger로 들어가도 이렇게 잘 뜬다 !

 

이번 포스팅으로 느낀 건 정말,,,, 하나의 라이브러리도 계속 변하니까 공식문서를 꼭꼭 참고하는 것을 염두에 둘 것 !!!!

---

참고

헷갈리던 MockMvcRestDocumentation.개념 정립

https://velog.io/@januaryone/Spring-Rest-Docs-%EC%82%AC%EC%9A%A9%EA%B8%B0

Spring Rest Docs 사용기

 

OpenAPI 버전 확인하는 법 도움을 받았습니다. 

(이 블로그에서는 Swagger를 도커로 실행시킴)

https://velog.io/@nefertiri/Spring-REST-Docs-%EC%99%80-Swagger-%EB%A5%BC-%EC%82%AC%EC%9A%A9%ED%95%98%EC%97%AC-API-%EB%AA%85%EC%84%B8%EC%84%9C-%EC%9E%91%EC%84%B1-%EC%9E%90%EB%8F%99%ED%99%94%ED%95%98%EA%B8%B0#swagger-ui-%EC%97%B0%EB%8F%99

Spring REST Docs 와 Swagger 를 사용하여 API 명세서 작성 자동화하기

 

SwaggerUI 의존성에 대해 해결하는데 도움을 받았습ㄴㅣ다 !!

https://colabear754.tistory.com/130

[Swagger] Spring Boot 3.0.X 버전에서 Swagger UI 접속 시 404 에러가 발생할 때