[SpringBoot] Springdoc Swagger 적용

서론

현재 진행 중인 프로젝트에 Spring Rest Docs를 적용하려 했으나, 팀원들이 각 API마다 테스트 코드를 작성하는 데 부담을 느끼는 것 같아 우선 Swagger를 적용하기로 했습니다.

프로젝트에는 Spring Security가 적용되어 있고, 멀티 테넌시를 위해 커스텀 헤더를 전달해야 했기 때문에 Swagger 적용이 쉽지 않았습니다.

비슷한 환경에 계신 분들께 도움이 되길 바라며, 부족하지만 Springdoc Swagger 적용기를 공유합니다.

 

개발 환경

• SpringBoot 2.6.3
• java 1.8
• springdoc-openapi-ui 1.6.11

 

빨리 SpringBoot 3.2.X 버전 + JDK 21로 넘어가서 Virtual Thread 다루어 보고 싶다....

 

Springfox vs Springdoc

Swagger UI를 제공하는 라이브러리는 Springfox와 Springdoc이 있습니다.

둘 중 Springdoc 라이브러리를 적용한 이유는 Springfox의 경우 2020년 7월 14일 이후 업데이트가 없는 반면 Springdoc은 꾸준히 업데이트를 진행 중이기 때문입니다.

또한, springdoc은 web flux도 지원하기 때문에 web flux를 사용 중인 모듈에도 적용할 수 있다는 장점도 있습니다.

 

springfox 4년 전 마지막 업데이트

springdoc

 

springdoc도 이를 인지하고 있기 때문에 공식문서에 springfox에서 springdoc로 마이그레이션 하는 방법을 제공합니다.

https://springdoc.org/#migrating-from-springfox

OpenAPI 3 Library for spring-boot

 

의존성 추가

SpringBoot 2.X 버전에는 단순히 springdoc-openapi-ui만 추가해주면 됩니다.

2024년 5월 28일 기준으로 가장 최신 버전은 1.8.0입니다.

 

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.11</version>
</dependency>

 

단, SpringBoot 3.X 버전부터는 springdoc-openapi-starter-webmvc-ui 라이브러리도 같이 추가해야 swagger-ui/index.html에 접속했을 때 404가 발생하지 않습니다.

2024년 5월 28일 기준으로 가장 최신 버전은 2.5.0입니다.

 

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

 

Swagger 기본 설정

Swagger를 설정하는 방법은 나름 간단합니다.

Configuration 클래스에 문서에 대한 기본 설명을 작성하고 application.properties 혹은 application.yml에 package-scan, swagger-ui.path와 같은 설정을 작성하면 됩니다.

 

SwaggerConfig.java

 

 

 

Swagger 관련 yml 설정

 

자세한 내용은 https://springdoc.org/#properties의 5번 항목을 참고하시면 됩니다.

OpenAPI 3 Library for spring-boot

 

springdoc-openapi core properties

 

 

swagger-ui.properties

 

Spring Security가 적용되어 있는 경우

Spring Security가 적용되어 있는 경우 우선 다음 경로들에 대해서 permitAll() 처리를 해줘야 합니다.

• /swagger-ui/**
• /swagger-resources/**
• /v3/api-docs/**

 

현재 프로젝트에서는 오픈 API를 제외한 모든 api에 대해 Bearer 인증이 필요하기 때문에 기본 설정에 다음과 같이 인증 설정을 추가했습니다.

 

 

 

그 결과 다음과 같이 각 api마다 자물쇠 아이콘이 생겼으며 자물쇠 아이콘 클릭 시 Bearer 토큰 정보 입력을 통한 인증이 가능해집니다.

 

 

Custom Header 추가

진행 중인 프로젝트는 멀티 테넌시 적용을 위해 커스텀 헤더를 추가했어야 하는데 이를 위해서는 OperationCustomizer를 Bean으로 등록해 주면 됩니다.

OperationCustomizer를 통해 swagger-ui에서 api 호출 시 header 뿐만 아니라 cookie 값도 넘겨받을 수 있습니다.

 

 

 

 

swagger-ui에 API 설명 등록

기본적으로 springdoc swagger는 application.properties 혹은 application.yml에서 package-scan 적용한 컨트롤러들을 모두 자동으로 swagger-ui에 등록합니다.

• 만약 등록하고 싶지 않은 api가 있다면 @Hidden 어노테이션을 통해 숨김 처리할 수 있습니다.

 

Springdoc에서는 Swagger UI를 위한 어노테이션이 Springfox 대비 변경되었으며 변경사항은 다음과 같습니다.

 

 

샘플로 간단하게 설명용 어노테이션을 적용한 결과는 다음과 같습니다.

 

 

 

마지막으로 swagger-ui를 통해 api를 호출한 결과 정상 응답을 받는 것을 확인할 수 있습니다.

 

 

참고

https://colabear754.tistory.com/99

[Spring Boot] Springdoc 라이브러리를 통한 Swagger 적용

https://kdev.ing/springdoc-ui-bearer-authentication/

SpringDoc UI 인증을 위한 토큰 기본값 표시

 

https://binux.tistory.com/161

[springdoc-openapi / Swagger] Failed to load remote configuration 이슈 해결

https://stackoverflow.com/questions/59560763/default-value-for-accept-header-using-springdoc-openapi

Default value for accept header using springdoc-openapi