새벽에 울면서 해결한 Spring 3.x.x Swagger 설정

YoungBin·2024년 3월 28일

React Spring boot Swagger

Spring boot

목록 보기

1/1

프로젝트를 시작 할려고 RestApi 테스트 환경을 준비 하고 있었는데 Swagger가 적용안되있는 것을 보고 설정을 하다가 3시간을 땅에다가 머리 박아버린 것에 대하여

사용 버전

springframework 3.1.4
dependency-management 1.1.3

필자는 Gradle을 사용하였지만 mavenrepository에 가면 다 있으니, 자신에 맞는 것을 사용하면 된다.

참고

spring 기반 어플리케이션에서 swagger 문서를 만들 때 사용하는 라이브러리가 2가지 있다.

Springfox
Springdoc

가 있는데 최신 개발 환경에 더 적합한 것은 SpringDoc이다.
그렇기에 필자는 Spring 3.1.4 + SpringDoc을 사용 할 것이다.

프로젝트 구성

필자는 Backend Spring boot / Front React로 구성을 하였다.

첫 번째 시도(실패)

Spring3 버전을 가지고 다음과 같이 설정을 하였다. spring3 버전 부터는 해당 의존성을 사용하지 않기에 ui 접속시 404에러가 뜬다.

implementation("org.springdoc:springdoc-openapi-ui:1.6.11")

이 내용은 검색 하니 금방 나왔다.

두 번째 시도(실패)

Spring3 버전 부터는 2.0.2을 사용해야 한다고 해서 다음과 같이 의존성을 추가 했다.

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2")

의존성을 추가를 하고 다음과 같이 Swagger 설정도 해주었다.

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() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }
 
    private Info apiInfo() {
        return new Info()
                .title("API Test")					// API 제목
                .description("API 테스트 swagger")	// API에 대한 설명
                .version("1.0.0");
    }
}

다음과 같이 TestController도 만들어주었다.

@RestController
public class TestController {
    @GetMapping(value = "/test")
    public String test(){
        return "test";
 }

이때 부터 의미 없는 컴퓨터와의 대화가 시작 되었다. Grable clean, IntelliJ제시작, 컴퓨터 껐다가 키기 등등 개발자 민간신앙 이란 것은 다 했다. 그래도 안됬다. 진짜 글이란 글은 다 보면서 민간신앙도 빠짐없이 해줬다.

하지만 여전히 404가 나를 반겼다.

세 번째 시도(성공)

우리의 위대하신 ChatGpt4님께 상황과 상황을 지금까지 시도한 것을 전부 알려드리고 질문을 드렸다. 그러자 문득 한 문장이 눈에 들어왔다.

그렇다. 필자는 이번에 Spring boot와 React을 사용하기 위해 web이 아닌 webflux을 사용하였다.

	implementation 'org.springframework.boot:spring-boot-starter-webflux'

설마 하는 마음으로 다음과 같이 의존성을 수정 해주었다.

	implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.0.2'

http://localhost:8080/webjars/swagger-ui/index.html 으로 접속하니 성공 했다!!!!

평소에 안하던 방식으로 프로젝트를 만들다보니 이런일들이 있었다.

결론

Spring boot에는 web와 webflux이 존제 하는데 webflux는 Spring Framwork5에서 새롭게 추가된 모듈이다. web-flux는 client, server에서 reactive 스타일의 어플리케이션 개발을 도와주는 모듈이라고 한다.

그렇기에 일반적으로 선언하고 추가 하는 것이 조금 다르다.

  implementation 'org.springframework.boot:spring-boot-starter-webflux'
  implementation 'org.springframework.boot:spring-boot-starter-web'

그런 것들을 위하여 SpringDoc도 web버전과 webflux으로 나눠져 있다.

    implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.0.2'
    implementation 'org.springdoc:springdoc-openapi-starter-web-ui:2.0.2'

그 점을 생각하여 라이브러리를 추가 하길 바란다.

그리고 필자와 같은 환경에서 설정을 하면 Swagger url 앞에 webjars이 붙을 수도 있는데 이 것은 Spring boot에서 SpringDoc을 사용할 때 webjars 경로가 자동으로 설정 될 수 있는 이유는 Spring boot의 내장된 헨들러가 /webjars/ 경로로 요청이 들어오면 webjars컨텐츠를 제공 하도록 구성 되어있기 때문이라고 한다.

해당 내용은 다음과 같은 설정으로 변경 가능하다.
application.properties

springdoc.swagger-ui.path=/swagger-ui

다음과 같이 설정을 하면 http://localhost:8080/swagger-ui으로도 접근이 가능해진다.

YoungBin