Spring Boot에 Swagger 연동하는 방법과 몇 가지 사용법

1. build.gradle 설정

gradle 기준으로 아래와 같이 build.gradle의 dependencies 에 swagger library를 추가해준다.

implementation("io.springfox:springfox-swagger-ui:2.9.2")
implementation("io.springfox:springfox-swagger2:2.9.2")

2. Swagger Configuration 클래스 생성

swagger 관련 Configuration 클래스를 만들어 준다.
restAPI() 의 basePackage 와 apiInfo() 에 들어갈 정보는 본인의 소스에 맞게 적어주면 된다.
uiConfig() 에서는 swagger_ui.html로 메소드들을 보여주는 방법을 정의할 수 있다.
필자는 UiConfigurationBuilder 를 통해서 docExpansion을 DocExpansion.LIST 로 하여 메소드를 펼쳐서 상세까지 보이게 설정했다.

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.DocExpansion;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket restAPI() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.fourtwod"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
                .docExpansion(DocExpansion.LIST)
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ASAP API")
                .description("42D Project")
                .version("1.0")
                .build();
    }
}

• 기본 값
  

• DocExpansion.LIST 세팅 후
  

3. 적용 예제

이제 세팅은 끝났으니, 컨트롤러에 swagger 설정을 해보자

@Api(tags = {"사용자 API"})
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/user")
public class UserApiController {

    private final UserService userService;

    @PatchMapping("/nickname/{flag}")
    @ApiOperation(value = "닉네임 체크/저장", response = ApiResult.class)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "flag", value = "유효성 체크(0), 유효성 체크 및 저장(1)", required = true
                    , dataType = "int", paramType = "path", example = "0")
            , @ApiImplicitParam(name = "userDto", value = "사용자 DTO\nnickname: 닉네임", required = true
                    , dataType = "UserDto", paramType = "body")
    })
    public ApiResult checkOrUpdateNickName(@PathVariable int flag, @RequestBody UserDto userDto, @ApiIgnore @LoginUser SessionUser user) throws Exception {
        if (user != null ) {
            ResponseCode responseCode = userService.checkOrUpdateNickName(flag, userDto.getNickname(), user);
            return new ApiResult<>(responseCode);
        } else {
            throw new Exception();
        }
    }
}

@Api

• 컨트롤러 api 이름을 정의한다

@ApiOperation

• api 메소드 이름과 응답값을 정의한다

@ApiImplicitParams

• 사용되는 파라미터에 대한 이름(name), 설명(value), 필수사항(required), 타입(dataType), 파라미터 종류(paramType), 예시(example), 초기값(defaultValue) 등을 세팅한다
  • 주의 사항
    • name: 메소드 파라미터에 사용되는 이름과 일치시켜야 한다
    • dataType: 전달받을 객체 타입을 정의한다. 단 숫자는 int, 문자는 string으로 정의한다

위와 같이 세팅하면 아래와 같이 확인이 가능하다.