Spring Boot 2.7.7 버전 프로젝트 swagger-ui를 이용한 API documentation 적용기

들어가며..

개발 공부를 틈틈이 하고자, 이전에 구현했던 프로젝트를 리팩터링 하고 새로운 기능을 구현하거나 기술을 적용하는 과정을 최근 들어 진행하고 있습니다.

Swagger

오늘은 그 중에서 swagger를 이용해 API 문서화를 하면, 협업 과정에서도 좋고, 별도로 문서를 따로 만들 필요가 없을 것 같다는 생각이 들어서 적용했고, 그 과정을 기록하려 합니다.

---

프로젝트 개발 환경

개발 환경	버전
Java	1.11
Spring Boot	2.7.7
Build 관리 도구	Gradle
Swagger	3
springdoc openapi ui	1.6.11

 

---

spring fox vs spring doc 선택 과정과 이유 🐾

우선 swagger를 Spring project에서 사용하기 위해서 크게 두 가지 선택지가 있었습니다.

• spring doc
• spring fox

https://github.com/springdoc/springdoc-openapi

GitHub - springdoc/springdoc-openapi: Library for OpenAPI 3 with spring-boot

https://github.com/springfox/springfox

GitHub - springfox/springfox: Automated JSON API documentation for API's built with Spring

 

간단하게, repository 확인 결과 여전히 spring doc은 원활하게 사용되고 관리되는 반면(커뮤니티 활성화가 잘 되어 있음), spring fox는 그렇지 않음을 알 수 있었습니다.

 

따라서 사용 편의성과 디자인 적인 UI 커스터마이징 툴을 제공하고, spring boot annotation 기반으로 동작한다는 장점들로 인해 spring doc✅을 이용해 swagger-ui를 적용하고, API 문서화를 진행하기로 결정!

 

spring doc 사용에 따라 의존성을 다음과 같이 추가합니다.

implementation 'org.springdoc:springdoc-openapi-ui:1.6.11'

 

Spring Boot 3 이후 부터는 springdoc-openapi-starter-webmvc-api을 추가해야 합니다!

 

---

Configuration 코드 작성과 annotation을 이용한 API spec 작성

spring doc을 사용하는 경우 Swagger 사용을 위한 별도의 configuration 클래스를 작성해줘야 하고, yml 파일을 이용해  필요한 설정을 작성해야 합니다.

 

Configuration class 작성

@Tag, @Operation annotation을 이용해 문서화에 들어갈 설명 작성

저는 위와 같이 작성해서 사용하겠습니다.

yaml 파일에 설정 정보 추가

자세한 설명은 다음 문서를 참고하면 좋을 것 같습니다.

https://springdoc.org/#properties

OpenAPI 3 Library for spring-boot

 

추가로 프로젝트에 Spring Security를 이용한 권한 설정이 되어 있어 다음과 같이 권한을 추가했습니다.

.antMatchers("/swagger-ui.html").permitAll()

 

---

트러블 슈팅 (빈 페이지만 조회되는 문제 상황) 😵‍💫

뭔 문제지..??

html 페이지 자체는 제대로 가져오나, js, css 파일을 가져오는데 실패해 빈 페이지를 가져오는 문제를 확인했고

→ 이에 대한 권한을 Security Configuration 설정에서 추가하여 문제 해결했습니다.

 

이에 따라 다음 경로들을 추가합니다

• /swagger-ui.html
• /swagger-ui/**
• /v3/api-docs/**

크게 세 가지 유형의 경로로 구성되는데, 각각

• swagger-ui 페이지에 접근하기 위한 경로
• 페이지 ui에 필요한 css, js 파일들을 위한 경로
• open-api spec에 접근하기 위한 경로

에 해당합니다.

이렇게 String 배열로 만들어서 추가했습니다.

 

---

적용 성공 👍🏼

description 이고 뭐고 제대로 설정하진 않았으나 적용 성공

 

 

---

앞으로 해결해야 할 문제들

적용은 성공했으나, 실제 테스트를 위해서는

• 권한 관리
• description 추가 작성
• 등등

을 구현해야 할 것 같고

 

추가 기능을 구현하고, 만료된 DBMS도 다시 세팅하고, EC2 instance에 배포하기 위해 CI/CD 과정 제대로 구축하는 등.. 할 일이 많은 것 같습니다..

 

---

참고한 글들

https://velog.io/@sheltonwon/Spring-Boot-Failed-to-load-API-definition

[Spring Boot] Failed to load API definition

https://recordsoflife.tistory.com/342

OpenAPI 3.0을 사용하여 Spring REST API 문서화

https://springdoc.org

OpenAPI 3 Library for spring-boot

https://velog.io/@letskuku/%ED%8A%B8%EB%9F%AC%EB%B8%94%EC%8A%88%ED%8C%85-swagger-ui%EA%B0%80-%EB%B9%88-%ED%99%94%EB%A9%B4%EC%9C%BC%EB%A1%9C-%EB%82%98%EC%98%A4%EB%8A%94-%EB%AC%B8%EC%A0%9C-%ED%95%B4%EA%B2%B0%ED%95%98%EA%B8%B0

[트러블슈팅] swagger-ui가 빈 화면으로 나오는 문제 해결하기