요즘 업무적으로 큰 이슈가 없기도하고해서 회사 프로젝트에 쓰인 기술들을 뜯어보는 시간을 가지고있다

회사 프로젝트에서는 kafka, aop, swagger 등등 여러가지가 적용되어 있지만
나는 세팅해본적도 사용해본적도 수정해본적도 없다

그 중에 엑셀파일을 다루는 POI 라이브러리를 뜯어보려고 했었다

회사 프로젝트에는 POI를 모듈화하여 사용하고 있으며, 나는 그저 그 모듈 사용방법에 맞게 쓰기만했고 자세한 내용은 알지못했다

혼자 실습하면서 프론트 화면까지는 좀 힘들것 같아서 포스트맨으로 api를 호출해볼까 하다가도 이참에 swagger 도 함께 세팅해보면 좋겠다는 생각에 프로젝트 세팅을 준비했다

swagger

swagger란?

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.
출처: 위키백과

Springfox / Springdoc

스웨거를 사용하기 위해서는 디펜던시를 추가해주어야한다.
springfox 와 springdoc 라이브러리 중 하나를 추가해주면 되는데, 저 둘에 대한 설명은 다른 분들이 엄청 자세히 설명해주고 있기때문에 나는 생략하겠다

SpringBoot 3.X 버전에서는 Springfox 라이브러리는 사용이 불가능하다
(이걸 모르고 5일 내내 삽질 한걸 생각하면...🤦🏻‍♀️)
Springfox 에서 아직 해결되지 않은 이슈이기 때문에 SpringBoot 3 을 쓰시는 분들은 꼭 Springdoc 을 이용하세요

Springdoc 을 이용한 Swagger 사용

build.gradle

글 작성일 기준으로 가장 최신버전인 1.6.14를 추가해준다

	implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

• 추가(23.02.16)
  springdoc-openapi-starter-webmvc-ui 도 함께 추가해주어야 화면이 출력된다
• 추가(23.03.23)
  org.springdoc:springdoc-openapi-ui 없어도 스웨거 사용하는데에 문제가 없다

application.yml

yml 파일을 작성해준다
springfox 는 config 파일에 세팅이 가능한것 같았는데 springdoc 은 yml(또는 properties) 파일에 세팅해준다

springdoc:
  packages-to-scan: com.example.demo
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /api-docs/json
    groups:
      enabled: true
  cache:
    disabled: true

Config

스웨거에서 보여질 정보들을 세팅해준다

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
            .title("POI 라이브러리 실습")
            .version("1.0")
            .description("POI 라이브러리를 이용한 엑셀 다운로드 실습 - 세팅부터 개발완료까지");

        return new OpenAPI()
            .components(new Components())
            .info(info);
    }
}

완성

이렇게 세팅이 완료된 뒤 http://localhost:8080/swagger-ui/index.html 에 접속하면 영롱하고 아름다운 swagger ui 가 나타나게된다

회고

Springfox 가 SpringBoot 3 에서 작동하지 않는다는 내용을 대충 봤었는데 대수롭지 않게 여긴 과거의 나를 반성한다
아니었음 진즉 swagger 세팅을 완료하고 신나신나 개발을 했을텐데...
앞으로는 공식 문서를 잘 보는 습관을 길러야지(그 전에 영어공부도)
그래도 이 덕에 오랜만에 블로그에 글을 쓰고싶어지는 계기가 되어서 해피엔딩이라고 생각한다

도움 받은 글

Spring boot Swagger 3.0 적용하기
[Java/Library] Swagger 이해하고 적용하기 : SpringDoc openAPI UI