[SpringBoot] Swagger 적용하기

[사용환경] #java 11 #springboot-2.7.6 #gradle build #Swagger-3.0.0

 

Api를 만들게되면 일반적으로 화면이 없어서 응답값과 요청값에 해당하는 문서를 따로 만들어줘야한다

이런 수고로움을 덜어줄 수 있는 도구가 스웨거이다.

스웨거를 사용해봤지만 처음부터 스웨거를 설정해준적이 없어서 직접 적용해보게 되었다

스프링부트와 그래들의 최신 버전으로 적용을 하다보니

검색해도 설정방법이 조금씩 다르게 되어있어서 나의 기준으로 다시 한번 정리하게 되었다.

 

<dependencies 추가> 

dependencies {
   implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

 

<Config 추가>

package com.EMarket.webService.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.EMarket.webService"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Practice Swagger")
                .description("practice swagger config")
                .version("1.0")
                .build();
    }

    //swagger ui 설정.
    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
                .displayRequestDuration(true)
                .validatorUrl("")
                .build();
    }
}

 

#Swagger-ui

버전별 swagger-ui 접속 url이 다르다

로컬에서 프로젝트를 구동 후 본인의 설정에 따른 url로 접속하면 된다.

Swagger2: http://localhost:8080/swagger-ui.html
Swagger3: http://localhost:8080/swagger-ui/index.html

 

 

<정상화면>

http://localhost:8080/swagger-ui/index.html

 

 

 

 

 

#적용하면서 발생한 오류 케이스1

build.gradle에 dependencies를 추가해 줄 경우 

implementation group: 'io.springfox', name: 'springfox-swagger', version: '3.0.0'

이런식으로 적었더니 오류가 났고 아래처럼 적어주라는 메세지가 나와서 수정했다

implementation 'io.springfox:springfox-boot-stater:3.0.0'

 

#적용하면서 발생한 오류 케이스2

implementation 'io.springfox:springfox-boot-stater:3.0.0'

이렇게 설정을 추가해주고 gradle에서도 의존성을 확인해봤다.

잘못된 gradle Dependencies

 

그럴듯하게 디펜던시가 추가되어있었지만 실제로는 에러가 발생했다

 

io.springfox:springfox-boot-stater:3.0.0을 찾을 수 없다고 나타났다

 

<정상적인 dependency>

implementation 'io.springfox:springfox-boot-starter:3.0.0'

오탈자로 인하여 발생한 오류였고 수정해서 gradle reload를 해주면 정상화면을 확인할 수 있다.

정상적인 dependencies

 

 

#적용하면서 발생한 오류 케이스3

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

어쩌고 저쩌고...

2022-12-31 01:55:02.518 ERROR 92739 --- [  restartedMain] o.s.boot.SpringApplication               : Application run failed

        org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
        at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.24.jar:5.3.24]
        at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.24.jar:5.3.24]
        at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.24.jar:5.3.24]
        at java.base/java.lang.Iterable.forEach(Iterable.java:75) ~[na:na]

 

application.yml에 아래 설정값을 추가하니 정상구동이 되었다.

 

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

 

 

에러 코드로 검색해보니 인프런에서 비슷한 케이스의 질문과 답변이 있어서 해결하였다.

댓글단 사람중에 아래와 같은 답변을 해주신분이 계셨는데 나의 오류케이스도 이에 해당하는것 같다.

"Spring boot 2.6버전 이후에 spring.mvc.pathmatch.matching-strategy 값이 ant_apth_matcher에서 path_pattern_parser로 변경되면서 몇몇 라이브러리(swagger포함)에 오류가 발생한다고 하네요. "

 

 

#참고 사이트

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

 

https://springfox.github.io/springfox/docs/current/

Springfox Reference Documentation

 

https://github.com/springfox/springfox/tree/master/springfox-boot-starter

GitHub - springfox/springfox: Automated JSON API documentation for API's built with Spring