[기록] spring boot 3에서의 swagger 구축

Geunhyung Pyun·2024년 6월 2일
Spring bootSwagger

Spring

목록 보기
4/4

배경

Spring boot 3 버전에서 swagger를 구축하고자 하였다. 평소처럼 하였으나 에러가 나는 것이었다.
에러 로그를 보면서 찾아보다가 내가 한 가지 간과한 게 있었다는 것을 발견하였다.

업무에 있었을 때는 jdk11을 기반으로 한 spring boot 2 버전을 자주 사용했었다.
그래서 springfox 쪽의 swagger를 사용을 많이 했는데
이번에 개인적으로 하는 프로젝트에서 사용한 것은 jdk 21을 기반으로 한 spring boot 3버전인 것이다.

이게 무슨 문제가 되는 것이냐 한다면
springfox는 2020년 7월 이후로 업데이트가 되지 않는다는 것이다. 그래서 OpenApi 3과 spring boot 3을 지원하지 않는다는 것이다.

그래서 생긴 것이 springfox 대신 생긴 것이 springdoc이다.

swagger

일단 먼저 swagger가 뭔지를 알아야 한다.

수동으로 작업했던 시기에는 API 문서화 작업에 있어서 반복되는 작업이 많고 API 스펙에 있어 변경이 생긴다면 직접 추적해야하는 번거로움이 있었다. API 테스트 실행에 있어서도 외부 프로그램인 Postman을 이용해서 작업하였거나 직접 테스트를 할 수 밖에 없었다.

이것을 자동화한 것이 swagger이다.
REST 웹 서비스를 설계, 빌드, 문서화 하는 데에 있어서 도와주는 오픈 소스 소프트웨어 프레임워크이다.
주로 문서 자동화를 지원하고 테스트 케이스 생성, 코드 생성 지원을 한다.

springdoc

swagger는 오픈 소스 프레임워크이지 java, spring을 위한 프레임워크가 아니다. OpenAPI를 위한 프레임워크이기에 굳이 java나 spring뿐만 아니라 python, js 환경에서도 사용이 가능하다.

spring 환경에서 사용이 가능하도록 설정을 해줘야 하는데 이러한 작업을 해주는 라이브러리로 2가지가 존재한다.
이게 바로 springfox, springdoc이다.

사용 방법

  1. build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'
  1. configuration
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@RequiredArgsConstructor
public class SwaggerConfiguration {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("테스트")
                        .version("1.0")
                        .description("테스트 설명"));
    }
}

OAS(Open API Specification)는 Rest API를 기술하는 표준이다. OpenAPI에 대한 명세가 필요하기 때문에 위와 같은 코드를 작성해야 한다.

참고

profile
Geunhyung Pyun
개발자를 원하는 사람.
이전 포스트

[Spring] jcenter

0개의 댓글