Spring Boot - Swagger 적용

Swagger란?

프로젝트 내 API를 Swagger 설정을 통해 자동으로 문서화해주는 도구로

사람이 일일이 작업할 필요 없이 프로젝트 실행을 통해
코드 내에서 변경사항(return 유형이나 parameter 수 변경 등)이 발생하여도 바로 자동으로 API문서를 만들어주므로 
매우 편리한 도구이다.

또한 UI를 통해 쉽게 API 목록 조회와 API 호출을 통한 테스트를 직접 해볼 수 있다..

Swagger UI

 

 

이를 적용하기 위해 아래 사이트를 참고하였으나

https://www.tutorialspoint.com/spring_boot/spring_boot_enabling_swagger2.htm

Spring Boot - Enabling Swagger2 - Tutorialspoint

 

아래와 같이 org.springframework.plugin.core의 메서드를 찾을 수 없어 실행조차 못하고..

org.springframework.plugin.core.PluginRegistry.getPluginFor(Ljava/lang/Object;Lorg/springframework/plugin/core/Plugin;)Lorg/springframework/plugin/core/Plugin;

 

구글링 결과 아래 이슈를 통해 springBootVersion=2.2.0.M1 에서는 사용이 안 되는 버그가 있다는 것을 알았다.ㅠㅜ

https://github.com/springfox/springfox/issues/2932

Issue when using Swagger latest version 2.9.2 with Spring boot 2.2.0 · Issue #2932 · springfox/springfox

 

일부 아래 plugin를 추가하여 된 사람이 있다곤 하는데, 내 경우 코드가 충돌이 나면서 에러가 발생하였다..

        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>1.2.0.RELEASE</version>
        </dependency>

 

 

다른 방법을 찾던 중 springdoc이란 걸 발견하였다.
springdoc도 Springfox와 같이 Swagger UI를 제공하면서
webflux라는 논 블록킹 비동기 방식의 웹 개발도 지원한다고 한다.

 

아래 Swggerfox vs Springdoc 비교 참고

https://junho85.pe.kr/1583?category=177748

Swagger. Springfox-Swagger 그리고 Springdoc

 

 

적용은 springdoc 공식문서를 참고하였다.

https://springdoc.org/

springdoc-openapi

 

추가로 적용 후

http://server:port/context-path/swagger-ui.html 을 통해 Swagger UI에 접근이 가능한데

나 같은 경우 화면이 나오질 않았다...(산 넘어 산)

혹시 나처럼 화면 안 보이는 경우 아래를 확인하자.

 

Spring Security 설정이 있는 경우.
다음과 같은 swagger 경로를 허용하도록 한다.

@Configuration
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {

    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/v3/api-docs",
                                   "/v3/api-docs/**",
                                   "/swagger-ui.html",
                                   "/swagger-ui/**");
    }

}

 

 

/v3/api-docs 접속은 가능하나 /swagger-ui.html은 안 되는 경우
Application클래스에 @EnableWebMvc 설정이 혹시 있는지 확인한다
Spring boot  2.2.4 이후 버전부터는 @EnableWebMvc가 이미 내장되어 있다. 이경우 오히려 제거해주어야 한다.

 

https://github.com/springdoc/springdoc-openapi/issues/150

Could not resolve view with name 'redirect:/swagger-ui/index.html?url=/v3/api-docs&validatorUrl=' · Issue #150 · springdoc/spr