[SpringBoot] Swagger 2.x 기반에서 swagger-ui.html 확인 방법

오래된 레거시를 보니 swagger 1.x 기반이었는데, 세팅이 되다 말았는지 ui 형태로 볼수가 없었다. 그래서 과감하게 3.x 로 넘어가려고 했는데 오류가 나서 2.x 로 띄운걸 정리하고자 한다. 버전별로 swagger 를 볼 수 있는 주소가 다른데, 2.x 버전대는 정상적으로 세팅했다면 8080 포트로 띄웠다고 가정하면, 아래와 같은 url 로 로컬에서 확인이 가능하다. (참고로 swagger 버전별로 저 주소패턴도 달라진다)

• API 주소 : http://127.0.0.1:8080/v2/api-docs
• UI 주소 : http://127.0.0.1:8080/swagger-ui.html

의존성 추가하기

우선 과거에 있던 swagger 1.x 버전대는 제거하고 다음과 같이 maven 의존성을 추가했다.

참고로 나는 스프링부터 1.4.x 버전으로 꽤 낮은 버전인데도 swagger 2.x 버전대로 잘 동작했으니 참고하자.

 

pom.xml

<dependencies>
...
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
...
</dependencies>

스프링부트 설정 코드 추가

스프링부트에서 Swagger 관련 정보를 추가하고, swagger-ui.html 을 로딩할 수 있도록 세팅하는 단계이다.

 

 

SwaggerConfig 관련 클래스 추가

package com.mypackage.sample;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfig {

  /**
   * Swagger API 세팅.
   *
   * @return Swagger api 리턴
   */
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .useDefaultResponseMessages(false)
      .apiInfo(getApiInfo())
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.mypackage.sample")) // 로딩될 패키지명
      .paths(PathSelectors.any())
      .build();
  }

  /**
   * API 정보.
   * @return API 정보를 담은값
   */
  public ApiInfo getApiInfo() {
      return new ApiInfoBuilder()
              .title("헬로 Swagger")
              .description("API 를 확인해봅시다.")
              .version("1.0")
              .build();
  }
}

Controller 에 정보 추가하기

지금까지는 Swagger2 를 보기위한 세팅이었고, Swagger 에서 정보를 추가하려면 Contoller 에서 swagger 용 어노테이션을 추가해줘야한다. 아래와 같이 @Api , @ApiOperation, @ApiParam 같은 어노테이션이 정보를 추가로 보여주기위한 용도이다.

 

참고로, swagger-ui 를 보는데, 로그에 다음과 같은 오류가 난다면, @ApiParam 에서 example 값을 채워주면 해결된다.

보통, PathVariable 의 타입이 long, int 인데, 빈값을 "" 으로 사용하려다가 실패난 케이스로 추정된다.

java.lang.NumberFormatException: For input string: ""

 

Swagger 어노테이션을 추가한 코드 샘플

//---- swagger 관련 어노테이션 start ------
@Api(value = "SampleContoller")
@SwaggerDefinition(tags = {@Tag(name = "SampleContoller",
        description = "샘플 컨트롤러")})
//---- swagger 관련 어노테이션 end ------        
        
@RestController
@RequestMapping("sample")
@ResponseBody
public SampleContoller {
...
  @ApiOperation(value = "delete sample",
    notes = "sample 에서 해당 id 기준의 값을 삭제한다.",
    httpMethod = "DELETE")
  @ResponseBody
  @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
  public void deleteSample(
      //---- swagger 관련 어노테이션 start ------
      @ApiParam(value = "sampleId", example = "1", defaultValue = "1", required = true)
      //---- swagger 관련 어노테이션 end ------     
      @PathVariable final Long sampleId) {
    sampleRepository.delete(sampleId);
  }
...
}