먼저 Swagger 이해하기

Swagger는 API 개발을 위해 설계, 빌드, 문서화, 시각화 등 다양한 기능을 제공하는 도구 및 프레임워크입니다.
OpenAPI Specification(OAS) 표준을 사용하여 RESTful API를 기술합니다.

Swagger는 최근 RESTful API 개발에 필수고 3개의 도구가 있습니다.

• Swagger UI

  • API 문서를 시각적으로 보여주는 Swagger의 대표적인 도구입니다.
  • API의 엔드포인트, 파라미터, 메서드, 요청 및 응답 형식을 보여주고 실제 테스트도 할 수 있습니다.
    
    

• Swagger Editor

  • Swagger 문서를 작성하고 편집할 수 있는 도구입니다.
  • Swagger 문서는 자동화 되어 있지만, 상세 편집이 필요할 때 유용합니다.
    
    

• Swagger Codegen

  • OpenAPI 표준을 기반으로 API를 자동으로 생성하는 도구입니다.
  • 간단한 API 테스트에 유용하고, 복잡한 API는 사용을 지양하는 편이 좋습니다.
    
    

오류 및 원인

SpringBoot 3 버전부터 Springfox Swagger 3를 적용하면 오류가 발생합니다.

dependencies{
    implementation 'io.springfox:springfox-swagger-ui:3.0.0'
}

원인은 SpringBoot 3부터 Spring Framework 6와 Java 17을 기본으로 작동하기 때문입니다.
특히 JakartaEE로 전환되면서 javax. 패키지가 jakarta. 패키지로 변경됐습니다.

하지만, Springfox는 2020년 7월 3.0.0 버전을 마지막으로 업데이트가 중지됐습니다.
JakartaEE와 Java 17을 지원할리 만무합니다.

단기 해결책

SpringBoot 버전을 2.x로 다운그레이드 하는 방법이 있습니다.
하지만 Swagger 하나 때문에 프로젝트 버전을 낮추는 무모한 도전을 할 필요가 있을까요?

근본 해결책

Springdoc-OpenAPI라는 좋은 대체 라이브러리가 나왔습니다.
Springfox와 다르게 꾸준히 업데이트도 진행되고 있습니다.

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
}

Springdoc 주요 기능은 아래와 같습니다.
자세한 내용은 다음에 기회가 되면 다루도록 하겠습니다.

• 자동 OpenAPI 문서 생성
• Swagger UI 통합
• OpenAPI 커스터마이징 및 그룹화
• Spring Security 통합
• WebFlux 지원
• 외부 문서 통합
• Kotlin 지원
• 서드파티 라이브러리 통합

Spirngdoc-OpenAPI